Add installation manual and 'sculptor sample' command to initialize a…

…nd run sample easily

README

@@ -1,3 +1,40 @@
 Sculptor is a framework and command line interface that makes using Apache HBase much easier.
 
 Please see the doc at the wiki page.
+
+== Pre-requirements ==
+- Apache Ivy is required to build Sculptor
+- Apache HBase installed
+- Hadoop MapReduce (Sculptor MapReduce mode only)
+
+== Build ==
+$ cd sculptor
+$ ant 
+
+== Run Sculptor ==
+1. Copy sculptor folder to your HBase client
+
+2. Edit $SCULPTOR_HOME/sculptor, change HBASE_HOME variable to fit your environment
+
+3. For Sculptor MapReduce mode only, get your environment ready to run customized MapReduce jobs over HBase.
+   This usually requires the following steps:
+     - Add HBase and ZooKeeper jars to Hadoop classpath by:
+       $ echo "export HADOOP_CLASSPATH=$HBASE_HOME/hbase-0.9x.jar:$HBASE_HOME/lib/zookeeper-3.x.y.jar" >> hadoop-env.sh
+     - Let Hadoop know where HBase is running
+       $ ln -s $HBASE_HOME/conf/hbase-site.xml $HADOOP_HOME/conf/hbase-site.xml
+     - Add sculptor-sample.jar to Hadoop classpath.
+       The easiest way to do this is to drop sculptor-sample.jar to $HADOOP_HOME/lib directory.
+     - Sync the above changes across the cluster
+     - Restart Hadoop MapReduce
+
+4. Start Sculptor
+   $ sh $SCULPTOR_HOME/sculptor
+   sculptor> help
+
+5. To initialize and run the sample
+   $ sh $SCULPTOR_HOME/sculptor sample
+   sculptor> get from sc_item_data limit=1
+
+6. Run ad-hoc MapReduce via Sculptor
+   sculptor> set process mapreduce
+   sculptor> get from sc_item_data item_id>100

build.xml

@@ -16,7 +16,7 @@
    specific language governing permissions and limitations
    under the License.    
 -->
-<project name="sculptor" default="sample-jar" xmlns:ivy="antlib:org.apache.ivy.ant">
+<project name="sculptor" default="sample-test-jar" xmlns:ivy="antlib:org.apache.ivy.ant">
     <!-- some variables used -->
     <property name="lib.dir" value="lib" />
     <property name="build.dir" value="build" />
@@ -42,48 +42,71 @@
         <mkdir dir="${build.dir}/sample/classes" />
     </target>
 
-  <target name="framework-compile" depends="clean,resolve">
-    <javac 
-     encoding="UTF-8" 
-     srcdir="framework/src"
-     destdir="${build.dir}/framework/classes"
-     debug="true">
-        <classpath>
-            <fileset dir="${lib.dir}">
-                <include name="**/*.jar" />
-            </fileset>
-        </classpath>
-    </javac>
-  </target>
+    <target name="framework-compile" depends="clean,resolve">
+        <javac 
+         encoding="UTF-8" 
+         srcdir="framework/src"
+         destdir="${build.dir}/framework/classes"
+         debug="true">
+            <classpath>
+                <fileset dir="${lib.dir}">
+                    <include name="**/*.jar" />
+                </fileset>
+            </classpath>
+        </javac>
+    </target>
 
-  <target name="framework-jar" depends="framework-compile" description="Making sculptor-${version}.jar">
-      <jar jarfile="sculptor-${version}.jar"
-          basedir="${build.dir}/framework/classes">
-    </jar>
-  </target>
+    <target name="framework-jar" depends="framework-compile" description="Making sculptor-${version}.jar">
+        <jar jarfile="sculptor-${version}.jar"
+             basedir="${build.dir}/framework/classes">
+        </jar>
+    </target>
 
-  <target name="sample-compile" depends="framework-jar">
-    <javac 
-     encoding="UTF-8" 
-     srcdir="sample/src"
-     destdir="${build.dir}/sample/classes"
-     debug="true">
-        <classpath>
-            <fileset dir="${lib.dir}">
-                <include name="**/*.jar" />
-            </fileset>
-            <fileset dir="./">
-                <include name="*.jar" />
-            </fileset>
-        </classpath>
-    </javac>
-  </target>
+    <target name="sample-compile" depends="framework-jar">
+        <javac 
+         encoding="UTF-8" 
+         srcdir="sample/src"
+         destdir="${build.dir}/sample/classes"
+         debug="true">
+            <classpath>
+                <fileset dir="${lib.dir}">
+                    <include name="**/*.jar" />
+                </fileset>
+                <fileset dir="./">
+                    <include name="*.jar" />
+                </fileset>
+            </classpath>
+        </javac>
+    </target>
 
-  <target name="sample-jar" depends="sample-compile" description="Making sculptor-sample-${version}.jar">
-      <jar jarfile="sculptor-sample-${version}.jar"
-          basedir="${build.dir}/sample/classes">
-    </jar>
-  </target>
+    <target name="sample-jar" depends="sample-compile" description="Making sculptor-sample-${version}.jar">
+        <jar jarfile="sculptor-sample-${version}.jar"
+              basedir="${build.dir}/sample/classes">
+        </jar>
+    </target>
+
+    <target name="sample-test-compile" depends="sample-compile" description="Compiling sculptor sample test source">
+        <javac 
+         encoding="UTF-8" 
+         srcdir="sample/test"
+         destdir="${build.dir}/sample/classes"
+         debug="true">
+            <classpath>
+                <fileset dir="${lib.dir}">
+                    <include name="**/*.jar" />
+                </fileset>
+                <fileset dir="./">
+                    <include name="*.jar" />
+                </fileset>
+            </classpath>
+        </javac>
+    </target>
+
+    <target name="sample-test-jar" depends="sample-test-compile" description="Making sculptor-sample-${version}.jar with test source">
+        <jar jarfile="sculptor-sample-${version}.jar"
+              basedir="${build.dir}/sample/classes">
+        </jar>
+    </target>
 
   <!-- javadoc target -->
   <target name="javadoc" depends="clean">

ivy.xml

@@ -24,5 +24,7 @@
         <dependency org="org.apache.zookeeper" name="zookeeper" rev="3.3.3" transitive="false"/>
         <dependency org="commons-lang" name="commons-lang" rev="2.5" transitive="false"/>
         <dependency org="commons-logging" name="commons-logging" rev="1.1.1" transitive="false"/>
+        <dependency org="log4j" name="log4j" rev="1.2.16" transitive="false"/>
+        <dependency org="junit" name="junit" rev="4.10" transitive="false"/>
     </dependencies>
 </ivy-module>