diff --git a/akka-docs/index.rst b/akka-docs/index.rst index a9fdc508ad..f50be13dd6 100644 --- a/akka-docs/index.rst +++ b/akka-docs/index.rst @@ -7,6 +7,7 @@ Contents manual/why-akka manual/getting-started-first-scala manual/getting-started-first-java + manual/building-akka manual/fsm-scala .. pending/actor-registry-java @@ -15,7 +16,6 @@ Contents .. pending/agents-scala .. pending/articles .. pending/benchmarks -.. pending/building-akka .. pending/buildr .. pending/cluster-membership .. pending/companies-using-akka diff --git a/akka-docs/pending/building-akka.rst b/akka-docs/manual/building-akka.rst similarity index 54% rename from akka-docs/pending/building-akka.rst rename to akka-docs/manual/building-akka.rst index 31af34c687..3d4f4ca1a0 100644 --- a/akka-docs/pending/building-akka.rst +++ b/akka-docs/manual/building-akka.rst @@ -3,171 +3,185 @@ Building Akka This page describes how to build and run Akka from the latest source code. +.. contents:: :local: + + Get the source code ------------------- -Akka uses `Git `_ and is hosted at `Github `_. +Akka uses `Git `_ and is hosted at `Github +`_. -You first need Git installed on your machine. You can then clone the source repositories: -* Akka repository from ``_ -* Akka Modules repository from ``_ +You first need Git installed on your machine. You can then clone the source +repositories: -For example: +- Akka repository from ``_ +- Akka Modules repository from ``_ -:: +For example:: - git clone git://github.com/jboner/akka.git - git clone git://github.com/jboner/akka-modules.git + git clone git://github.com/jboner/akka.git + git clone git://github.com/jboner/akka-modules.git -If you have already cloned the repositories previously then you can update the code with ``git pull``: +If you have already cloned the repositories previously then you can update the +code with ``git pull``:: -:: + git pull origin master - git pull origin master SBT - Simple Build Tool ----------------------- -Akka is using the excellent `SBT `_ build system. So the first thing you have to do is to download and install SBT. You can read more about how to do that `here `_ . +Akka is using the excellent `SBT `_ +build system. So the first thing you have to do is to download and install +SBT. You can read more about how to do that `here +`_ . -The SBT commands that you'll need to build Akka are all included below. If you want to find out more about SBT and using it for your own projects do read the `SBT documentation `_. +The SBT commands that you'll need to build Akka are all included below. If you +want to find out more about SBT and using it for your own projects do read the +`SBT documentation +`_. -The Akka SBT build file is ``project/build/AkkaProject.scala`` with some properties defined in ``project/build.properties``. +The Akka SBT build file is ``project/build/AkkaProject.scala`` with some +properties defined in ``project/build.properties``. ----- Building Akka ------------- -First make sure that you are in the akka code directory: +First make sure that you are in the akka code directory:: -:: + cd akka - cd akka Fetching dependencies ^^^^^^^^^^^^^^^^^^^^^ -SBT does not fetch dependencies automatically. You need to manually do this with the ``update`` command: +SBT does not fetch dependencies automatically. You need to manually do this with +the ``update`` command:: -:: + sbt update - sbt update +Once finished, all the dependencies for Akka will be in the ``lib_managed`` +directory under each module: akka-actor, akka-stm, and so on. -Once finished, all the dependencies for Akka will be in the ``lib_managed`` directory under each module: akka-actor, akka-stm, and so on. +*Note: you only need to run update the first time you are building the code, +or when the dependencies have changed.* -*Note: you only need to run {{update}} the first time you are building the code, or when the dependencies have changed.* Building ^^^^^^^^ -To compile all the Akka core modules use the ``compile`` command: +To compile all the Akka core modules use the ``compile`` command:: -:: + sbt compile - sbt compile +You can run all tests with the ``test`` command:: -You can run all tests with the ``test`` command: + sbt test -:: +If compiling and testing are successful then you have everything working for the +latest Akka development version. - sbt test - -If compiling and testing are successful then you have everything working for the latest Akka development version. Publish to local Ivy repository ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you want to deploy the artifacts to your local Ivy repository (for example, to use from an SBT project) use the ``publish-local`` command: +If you want to deploy the artifacts to your local Ivy repository (for example, +to use from an SBT project) use the ``publish-local`` command:: -:: + sbt publish-local - sbt publish-local Publish to local Maven repository ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you want to deploy the artifacts to your local Maven repository use: +If you want to deploy the artifacts to your local Maven repository use:: -:: + sbt publish-local publish - sbt publish-local publish SBT interactive mode ^^^^^^^^^^^^^^^^^^^^ -Note that in the examples above we are calling ``sbt compile`` and ``sbt test`` and so on. SBT also has an interactive mode. If you just run ``sbt`` you enter the interactive SBT prompt and can enter the commands directly. This saves starting up a new JVM instance for each command and can be much faster and more convenient. +Note that in the examples above we are calling ``sbt compile`` and ``sbt test`` +and so on. SBT also has an interactive mode. If you just run ``sbt`` you enter +the interactive SBT prompt and can enter the commands directly. This saves +starting up a new JVM instance for each command and can be much faster and more +convenient. For example, building Akka as above is more commonly done like this: -:: +.. code-block:: none + + % sbt + [info] Building project akka 1.1-SNAPSHOT against Scala 2.9.0.RC1 + [info] using AkkaParentProject with sbt 0.7.6.RC0 and Scala 2.7.7 + > update + [info] + [info] == akka-actor / update == + ... + [success] Successful. + [info] + [info] Total time ... + > compile + ... + > test + ... - % sbt - [info] Building project akka 1.1-SNAPSHOT against Scala 2.8.1 - [info] using AkkaParentProject with sbt 0.7.5.RC0 and Scala 2.7.7 - > update - [info] - [info] == akka-actor / update == - ... - [success] Successful. - [info] - [info] Total time ... - > compile - ... - > test - ... SBT batch mode ^^^^^^^^^^^^^^ -It's also possible to combine commands in a single call. For example, updating, testing, and publishing Akka to the local Ivy repository can be done with: +It's also possible to combine commands in a single call. For example, updating, +testing, and publishing Akka to the local Ivy repository can be done with:: -:: + sbt update test publish-local - sbt update test publish-local - ----- Building Akka Modules --------------------- -To build Akka Modules first build and publish Akka to your local Ivy repository as described above. Or using: +To build Akka Modules first build and publish Akka to your local Ivy repository +as described above. Or using:: -:: + cd akka + sbt update publish-local - cd akka - sbt update publish-local +Then you can build Akka Modules using the same steps as building Akka. First +update to get all dependencies (including the Akka core modules), then compile, +test, or publish-local as needed. For example:: -Then you can build Akka Modules using the same steps as building Akka. First update to get all dependencies (including the Akka core modules), then compile, test, or publish-local as needed. For example: + cd akka-modules + sbt update publish-local -:: - - cd akka-modules - sbt update publish-local Microkernel distribution ^^^^^^^^^^^^^^^^^^^^^^^^ -To build the Akka Modules microkernel (the same as the Akka Modules distribution download) use the ``dist`` command: +To build the Akka Modules microkernel (the same as the Akka Modules distribution +download) use the ``dist`` command:: -:: + sbt dist - sbt dist +The distribution zip can be found in the dist directory and is called +``akka-modules-{version}.zip``. -The distribution zip can be found in the dist directory and is called ``akka-modules-{version}.zip``. +To run the mircokernel, unzip the zip file, change into the unzipped directory, +set the ``AKKA_HOME`` environment variable, and run the main jar file. For +example: -To run the mircokernel, unzip the zip file, change into the unzipped directory, set the ``AKKA_HOME`` environment variable, and run the main jar file. For example: +.. code-block:: none -:: + unzip dist/akka-modules-1.1-SNAPSHOT.zip + cd akka-modules-1.1-SNAPSHOT + export AKKA_HOME=`pwd` + java -jar akka-modules-1.1-SNAPSHOT.jar - unzip dist/akka-modules-1.1-SNAPSHOT.zip - cd akka-modules-1.1-SNAPSHOT - export AKKA_HOME=`pwd` - java -jar akka-modules-1.1-SNAPSHOT.jar +The microkernel will boot up and install the sample applications that reside in +the distribution's ``deploy`` directory. You can deploy your own applications +into the ``deploy`` directory as well. -The microkernel will boot up and install the sample applications that reside in the distribution's ``deploy`` directory. You can deploy your own applications into the ``deploy`` directory as well. - ----- Scripts ------- @@ -177,32 +191,38 @@ Linux/Unix init script Here is a Linux/Unix init script that can be very useful: -``_ +http://github.com/jboner/akka/blob/master/scripts/akka-init-script.sh Copy and modify as needed. + Simple startup shell script ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This little script might help a bit. Just make sure you have the Akka distribution in the '$AKKA_HOME/dist' directory and then invoke this script to start up the kernel. The distribution is created in the './dist' dir for you if you invoke 'sbt dist'. +This little script might help a bit. Just make sure you have the Akka +distribution in the '$AKKA_HOME/dist' directory and then invoke this script to +start up the kernel. The distribution is created in the './dist' dir for you if +you invoke 'sbt dist'. -``_ +http://github.com/jboner/akka/blob/master/scripts/run_akka.sh Copy and modify as needed. ----- Dependencies ------------ -If you are managing dependencies by hand you can find out what all the compile dependencies are for each module by looking in the ``lib_managed/compile`` directories. For example, you can run this to create a listing of dependencies (providing you have the source code and have run ``sbt update``): +If you are managing dependencies by hand you can find out what all the compile +dependencies are for each module by looking in the ``lib_managed/compile`` +directories. For example, you can run this to create a listing of dependencies +(providing you have the source code and have run ``sbt update``):: -:: + cd akka + ls -1 */lib_managed/compile - cd akka - ls -1 */lib_managed/compile -Here are the dependencies used by the Akka core modules. +Dependencies used by the Akka core modules +------------------------------------------ akka-actor ^^^^^^^^^^ @@ -247,8 +267,9 @@ akka-http * jsr250-api-1.0.jar * jsr311-api-1.1.jar ----- -Here are the dependencies used by the Akka modules. + +Dependencies used by the Akka modules +------------------------------------- akka-amqp ^^^^^^^^^