Information for Akka Developers, #22902
This commit is contained in:
Patrik Nordwall
parent
6d099cc8ad
commit
36571de29d
15 changed files with 68 additions and 446 deletions
|
|
@ -15,7 +15,6 @@
|
|||
* [common/other-modules](java/common/other-modules.md)
|
||||
* [java/howto](java/howto.md)
|
||||
* [java/scala-compat](java/scala-compat.md)
|
||||
* [dev/index](java/dev/index.md)
|
||||
* [project/index](java/project/index.md)
|
||||
* [additional/index](java/additional/index.md)
|
||||
|
||||
|
|
|
|||
|
|
@ -101,4 +101,4 @@ A `ByteStringBuilder` can be wrapped in a `java.io.OutputStream` via the `asOutp
|
|||
|
||||
## Architecture in-depth
|
||||
|
||||
For further details on the design and internal architecture see @ref:[I/O Layer Design](../scala/dev/io-layer.md).
|
||||
For further details on the design and internal architecture see @ref:[I/O Layer Design](common/io-layer.md).
|
||||
|
|
@ -14,7 +14,6 @@
|
|||
* [scala/index-utilities](scala/index-utilities.md)
|
||||
* [common/other-modules](scala/common/other-modules.md)
|
||||
* [scala/howto](scala/howto.md)
|
||||
* [dev/index](scala/dev/index.md)
|
||||
* [project/index](scala/project/index.md)
|
||||
* [additional/index](scala/additional/index.md)
|
||||
|
||||
|
|
|
|||
|
|
@ -717,12 +717,12 @@ and to the registered subscribers on the system event bus with the help of `clus
|
|||
|
||||
## How to Test
|
||||
|
||||
@ref:[Multi Node Testing](../scala/dev/multi-node-testing.md) is useful for testing cluster applications.
|
||||
@ref:[Multi Node Testing](../scala/multi-node-testing.md) is useful for testing cluster applications.
|
||||
|
||||
Set up your project according to the instructions in @ref:[Multi Node Testing](../scala/dev/multi-node-testing.md) and @ref:[Multi JVM Testing](../scala/dev/multi-jvm-testing.md), i.e.
|
||||
Set up your project according to the instructions in @ref:[Multi Node Testing](../scala/multi-node-testing.md) and @ref:[Multi JVM Testing](../scala/multi-jvm-testing.md), i.e.
|
||||
add the `sbt-multi-jvm` plugin and the dependency to `akka-multi-node-testkit`.
|
||||
|
||||
First, as described in @ref:[Multi Node Testing](../scala/dev/multi-node-testing.md), we need some scaffolding to configure the `MultiNodeSpec`.
|
||||
First, as described in @ref:[Multi Node Testing](../scala/multi-node-testing.md), we need some scaffolding to configure the `MultiNodeSpec`.
|
||||
Define the participating roles and their [cluster_configuration_scala](#cluster-configuration-scala) in an object extending `MultiNodeConfig`:
|
||||
|
||||
@@snip [StatsSampleSpec.scala]($akka$/akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsSampleSpec.scala) { #MultiNodeConfig }
|
||||
|
|
|
|||
|
|
@ -28,12 +28,7 @@ that the module or API wasn't useful.
|
|||
|
||||
These are the current complete modules marked as **may change**:
|
||||
|
||||
@@toc { depth=1 }
|
||||
* @ref:[Multi Node Testing](../../scala/multi-node-testing.md)
|
||||
* @ref:[Akka Typed](../../scala/typed.md)
|
||||
|
||||
@@@ index
|
||||
|
||||
* [../dev/multi-node-testing](../dev/multi-node-testing.md)
|
||||
* [../../scala/typed](../../scala/typed.md)
|
||||
|
||||
@@@
|
||||
|
||||
|
|
|
|||
|
|
@ -1,145 +0,0 @@
|
|||
# Building Akka
|
||||
|
||||
This page describes how to build and run Akka from the latest source code.
|
||||
|
||||
## Get the Source Code
|
||||
|
||||
Akka uses [Git](http://git-scm.com) and is hosted at [Github](http://github.com).
|
||||
|
||||
You first need Git installed on your machine. You can then clone the source
|
||||
repository from [http://github.com/akka/akka](http://github.com/akka/akka).
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
git clone git://github.com/akka/akka.git
|
||||
```
|
||||
|
||||
If you have already cloned the repository previously then you can update the
|
||||
code with `git pull`:
|
||||
|
||||
```
|
||||
git pull origin master
|
||||
```
|
||||
|
||||
## sbt
|
||||
|
||||
Akka is using the excellent [sbt](https://github.com/sbt/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 in the
|
||||
[sbt setup](http://www.scala-sbt.org/0.13/tutorial/index.html) 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](http://www.scala-sbt.org/documentation.html).
|
||||
|
||||
The main Akka sbt build file is `project/AkkaBuild.scala`, with a *build.sbt* in
|
||||
each subproject’s directory. It is advisable to allocate at least 2GB of heap size
|
||||
to the JVM that runs sbt, otherwise you may experience some spurious failures when
|
||||
running the tests.
|
||||
|
||||
## Building Akka
|
||||
|
||||
First make sure that you are in the akka code directory:
|
||||
|
||||
```
|
||||
cd akka
|
||||
```
|
||||
|
||||
### Building
|
||||
|
||||
To compile all the Akka core modules use the `compile` command:
|
||||
|
||||
```
|
||||
sbt compile
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
### Parallel Execution
|
||||
|
||||
By default the tests are executed sequentially. They can be executed in parallel to reduce build times,
|
||||
if hardware can handle the increased memory and cpu usage. Add the following system property to sbt
|
||||
launch script to activate parallel execution:
|
||||
|
||||
```
|
||||
-Dakka.parallelExecution=true
|
||||
```
|
||||
|
||||
### Long Running and Time Sensitive Tests
|
||||
|
||||
By default are the long running tests (mainly cluster tests) and time sensitive tests (dependent on the
|
||||
performance of the machine it is running on) disabled. You can enable them by adding one of the flags:
|
||||
|
||||
```
|
||||
-Dakka.test.tags.include=long-running
|
||||
-Dakka.test.tags.include=timing
|
||||
```
|
||||
|
||||
Or if you need to enable them both:
|
||||
|
||||
```
|
||||
-Dakka.test.tags.include=long-running,timing
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```
|
||||
sbt publish-local
|
||||
```
|
||||
|
||||
### sbt Interactive Mode
|
||||
|
||||
Note that in the examples above we are calling `sbt compile` and `sbt test`
|
||||
and so on, but 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:
|
||||
|
||||
```
|
||||
% sbt
|
||||
[info] Set current project to default (in build file:/.../akka/project/plugins/)
|
||||
[info] Set current project to akka (in build file:/.../akka/)
|
||||
> compile
|
||||
...
|
||||
> test
|
||||
...
|
||||
```
|
||||
|
||||
### sbt Batch Mode
|
||||
|
||||
It's also possible to combine commands in a single call. For example, testing,
|
||||
and publishing Akka to the local Ivy repository can be done with:
|
||||
|
||||
```
|
||||
sbt test publish-local
|
||||
```
|
||||
|
||||
<a id="dependencies"></a>
|
||||
## Dependencies
|
||||
|
||||
You can look at the Ivy dependency resolution information that is created on
|
||||
`sbt update` and found in `~/.ivy2/cache`. For example, the
|
||||
`~/.ivy2/cache/com.typesafe.akka-akka-remote-compile.xml` file contains
|
||||
the resolution information for the akka-remote module compile dependencies. If
|
||||
you open this file in a web browser you will get an easy to navigate view of
|
||||
dependencies.
|
||||
|
||||
## Scaladoc Dependencies
|
||||
|
||||
Akka generates class diagrams for the API documentation using ScalaDoc. This
|
||||
needs the `dot` command from the Graphviz software package to be installed to
|
||||
avoid errors. You can disable the diagram generation by adding the flag
|
||||
`-Dakka.scaladoc.diagrams=false`. After installing Graphviz, make sure you add
|
||||
the toolset to the PATH (definitely on Windows).
|
||||
|
|
@ -1,59 +0,0 @@
|
|||
# Developer Guidelines
|
||||
|
||||
@@@ note
|
||||
|
||||
First read [The Akka Contributor Guidelines](https://github.com/akka/akka/blob/master/CONTRIBUTING.md).
|
||||
|
||||
@@@
|
||||
|
||||
## Code Style
|
||||
|
||||
The Akka code style follows the [Scala Style Guide](http://docs.scala-lang.org/style/) . The only exception is the
|
||||
style of block comments:
|
||||
|
||||
```scala
|
||||
/**
|
||||
* Style mandated by "Scala Style Guide"
|
||||
*/
|
||||
|
||||
/**
|
||||
* Style adopted in the Akka codebase
|
||||
*/
|
||||
```
|
||||
|
||||
Akka is using `Scalariform` to format the source code as part of the build. So just hack away and then run `sbt compile` and it will reformat the code according to Akka standards.
|
||||
|
||||
## Process
|
||||
|
||||
The full process is described in [The Akka Contributor Guidelines](https://github.com/akka/akka/blob/master/CONTRIBUTING.md). In summary:
|
||||
|
||||
* Make sure you have signed the Akka CLA, if not, [sign it online](http://www.lightbend.com/contribute/cla).
|
||||
* Pick a ticket, if there is no ticket for your work then create one first.
|
||||
* Fork [akka/akka](https://github.com/akka/akka). Start working in a feature branch.
|
||||
* When you are done, create a GitHub Pull-Request towards the targeted branch.
|
||||
* When there's consensus on the review, someone from the Akka Core Team will merge it.
|
||||
|
||||
## Commit messages
|
||||
|
||||
Please follow the conventions described in [The Akka Contributor Guidelines](https://github.com/akka/akka/blob/master/CONTRIBUTING.md) when creating public commits and writing commit messages.
|
||||
|
||||
## Testing
|
||||
|
||||
All code that is checked in **should** have tests. All testing is done with `ScalaTest` and `ScalaCheck`.
|
||||
|
||||
* Name tests as **Test.scala** if they do not depend on any external stuff. That keeps surefire happy.
|
||||
* Name tests as **Spec.scala** if they have external dependencies.
|
||||
|
||||
### Actor TestKit
|
||||
|
||||
There is a useful test kit for testing actors: [akka.util.TestKit](@github@/akka-testkit/src/main/scala/akka/testkit/TestKit.scala). It enables assertions concerning replies received and their timing, there is more documentation in the <!-- FIXME: More than one link target with name akka-testkit in path Some(/dev/developer-guidelines.rst) --> akka-testkit module.
|
||||
|
||||
### Multi-JVM Testing
|
||||
|
||||
Included in the example is an sbt trait for multi-JVM testing which will fork
|
||||
JVMs for multi-node testing. There is support for running applications (objects
|
||||
with main methods) and running ScalaTest tests.
|
||||
|
||||
### NetworkFailureTest
|
||||
|
||||
You can use the 'NetworkFailureTest' trait to test network failure.
|
||||
|
|
@ -1,202 +0,0 @@
|
|||
# Documentation Guidelines
|
||||
|
||||
The Akka documentation uses [reStructuredText](http://docutils.sourceforge.net/rst.html) as its markup language and is
|
||||
built using [Sphinx](http://sphinx.pocoo.org).
|
||||
|
||||
## Sphinx
|
||||
|
||||
For more details see [The Sphinx Documentation](http://sphinx.pocoo.org/contents.html)
|
||||
|
||||
## reStructuredText
|
||||
|
||||
For more details see [The reST Quickref](http://docutils.sourceforge.net/docs/user/rst/quickref.html)
|
||||
|
||||
### Sections
|
||||
|
||||
Section headings are very flexible in reST. We use the following convention in
|
||||
the Akka documentation:
|
||||
|
||||
* `#` (over and under) for module headings
|
||||
* `=` for sections
|
||||
* `-` for subsections
|
||||
* `^` for subsubsections
|
||||
* `~` for subsubsubsections
|
||||
|
||||
### Cross-referencing
|
||||
|
||||
Sections that may be cross-referenced across the documentation should be marked
|
||||
with a reference. To mark a section use `.. _ref-name:` before the section
|
||||
heading. The section can then be linked with `:ref:`ref-name``. These are
|
||||
unique references across the entire documentation.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
.. _akka-module:
|
||||
|
||||
#############
|
||||
Akka Module
|
||||
#############
|
||||
|
||||
This is the module documentation.
|
||||
|
||||
.. _akka-section:
|
||||
|
||||
Akka Section
|
||||
============
|
||||
|
||||
Akka Subsection
|
||||
---------------
|
||||
|
||||
Here is a reference to "akka section": :ref:`akka-section` which will have the
|
||||
name "Akka Section".
|
||||
```
|
||||
|
||||
## Build the documentation
|
||||
|
||||
First install [Sphinx](http://sphinx.pocoo.org). See below.
|
||||
|
||||
### Building
|
||||
|
||||
For the html version of the docs:
|
||||
|
||||
```
|
||||
sbt sphinx:generateHtml
|
||||
|
||||
open <project-dir>/akka-docs/target/sphinx/html/index.html
|
||||
```
|
||||
|
||||
For the pdf version of the docs:
|
||||
|
||||
```
|
||||
sbt sphinx:generatePdf
|
||||
|
||||
open <project-dir>/akka-docs/target/sphinx/latex/AkkaJava.pdf
|
||||
or
|
||||
open <project-dir>/akka-docs/target/sphinx/latex/AkkaScala.pdf
|
||||
```
|
||||
|
||||
### Installing Sphinx on OS X
|
||||
|
||||
Install [Homebrew](https://github.com/mxcl/homebrew)
|
||||
|
||||
Install Python with Homebrew:
|
||||
|
||||
```
|
||||
brew install python
|
||||
```
|
||||
|
||||
Homebrew will automatically add Python executable to your $PATH and pip is a part of the default Python installation with Homebrew.
|
||||
|
||||
More information in case of trouble:
|
||||
[https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python](https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python)
|
||||
|
||||
Install sphinx:
|
||||
|
||||
```
|
||||
pip install sphinx
|
||||
```
|
||||
|
||||
Install BasicTeX package from:
|
||||
[http://www.tug.org/mactex/morepackages.html](http://www.tug.org/mactex/morepackages.html)
|
||||
|
||||
Add texlive bin to $PATH:
|
||||
|
||||
```
|
||||
export TEXLIVE_PATH=/usr/local/texlive/2016basic/bin/universal-darwin
|
||||
export PATH=$TEXLIVE_PATH:$PATH
|
||||
```
|
||||
|
||||
Add missing tex packages:
|
||||
|
||||
```
|
||||
sudo tlmgr update --self
|
||||
sudo tlmgr install titlesec
|
||||
sudo tlmgr install framed
|
||||
sudo tlmgr install threeparttable
|
||||
sudo tlmgr install wrapfig
|
||||
sudo tlmgr install helvetic
|
||||
sudo tlmgr install courier
|
||||
sudo tlmgr install multirow
|
||||
sudo tlmgr install capt-of
|
||||
sudo tlmgr install needspace
|
||||
sudo tlmgr install eqparbox
|
||||
sudo tlmgr install environ
|
||||
sudo tlmgr install trimspaces
|
||||
```
|
||||
|
||||
If you get the error "unknown locale: UTF-8" when generating the documentation the solution is to define the following environment variables:
|
||||
|
||||
```
|
||||
export LANG=en_US.UTF-8
|
||||
export LC_ALL=en_US.UTF-8
|
||||
```
|
||||
|
||||
### Installing Sphinx on Linux
|
||||
|
||||
Install Python with your package manager:
|
||||
|
||||
```
|
||||
apt-get install python # for Debian based systems
|
||||
yum install python # for CentOS/RHEL systems
|
||||
```
|
||||
|
||||
This will automatically add Python executable to your $PATH and pip is a part of the default Python installation. Remember you need *sudo* rights to run this command.
|
||||
|
||||
More information in case of trouble:
|
||||
[https://packaging.python.org/install_requirements_linux](https://packaging.python.org/install_requirements_linux)/
|
||||
|
||||
Install Sphinx:
|
||||
|
||||
```
|
||||
apt-get install python-sphinx # for Debian based systems
|
||||
#alternatively
|
||||
pip install sphinx
|
||||
```
|
||||
|
||||
For other Linux systems please check Sphinx website:
|
||||
[http://www.sphinx-doc.org/en/stable/install.html#other-linux-distributions](http://www.sphinx-doc.org/en/stable/install.html#other-linux-distributions)
|
||||
|
||||
Install TextLive:
|
||||
|
||||
```
|
||||
apt-get install texlive-latex-base texlive-latex-extra texlive-latex-recommended
|
||||
# additionally you may need xzdec
|
||||
apt-get install xzdec
|
||||
```
|
||||
|
||||
In case you get the following error:
|
||||
|
||||
>
|
||||
Unknown directive ...containerchecksum c59200574a316416a23695c258edf3a32531fbda43ccdc09360ee105c3f07f9fb77df17c4ba4c2ea4f3a5ea6667e064b51e3d8c2fe6c984ba3e71b4e32716955... , please fix it! at /usr/share/texlive/tlpkg/TeXLive/TLPOBJ.pm line 210, <$retfh> line 5579.
|
||||
|
||||
you need to specify you want to continue using the 2015 version:
|
||||
|
||||
```
|
||||
tlmgr option repository ftp://tug.org/historic/systems/texlive/2015/tlnet-final
|
||||
```
|
||||
|
||||
Add missing tex packages:
|
||||
|
||||
```
|
||||
sudo tlmgr update --self
|
||||
sudo tlmgr install titlesec
|
||||
sudo tlmgr install framed
|
||||
sudo tlmgr install threeparttable
|
||||
sudo tlmgr install wrapfig
|
||||
sudo tlmgr install helvetic
|
||||
sudo tlmgr install courier
|
||||
sudo tlmgr install multirow
|
||||
sudo tlmgr install capt-of
|
||||
sudo tlmgr install needspace
|
||||
sudo tlmgr install eqparbox
|
||||
sudo tlmgr install environ
|
||||
sudo tlmgr install trimspaces
|
||||
```
|
||||
|
||||
If you get the error "unknown locale: UTF-8" when generating the documentation the solution is to define the following environment variables:
|
||||
|
||||
```
|
||||
export LANG=en_US.UTF-8
|
||||
export LC_ALL=en_US.UTF-8
|
||||
```
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
# Information for Akka Developers
|
||||
|
||||
@@toc { depth=2 }
|
||||
|
||||
@@@ index
|
||||
|
||||
* [building-akka](building-akka.md)
|
||||
* [multi-jvm-testing](multi-jvm-testing.md)
|
||||
* [io-layer](io-layer.md)
|
||||
* [developer-guidelines](developer-guidelines.md)
|
||||
* [documentation](documentation.md)
|
||||
|
||||
@@@
|
||||
|
|
@ -19,5 +19,6 @@
|
|||
* [io-tcp](io-tcp.md)
|
||||
* [io-udp](io-udp.md)
|
||||
* [camel](camel.md)
|
||||
* [multi-jvm-testing](multi-jvm-testing.md)
|
||||
|
||||
@@@
|
||||
|
|
@ -101,4 +101,4 @@ A `ByteStringBuilder` can be wrapped in a `java.io.OutputStream` via the `asOutp
|
|||
|
||||
## Architecture in-depth
|
||||
|
||||
For further details on the design and internal architecture see @ref:[I/O Layer Design](../scala/dev/io-layer.md).
|
||||
For further details on the design and internal architecture see @ref:[I/O Layer Design](common/io-layer.md).
|
||||
|
|
@ -196,5 +196,5 @@ the sbt prompt.
|
|||
## Multi Node Additions
|
||||
|
||||
There has also been some additions made to the `SbtMultiJvm` plugin to accommodate the
|
||||
@ref:[may change](../common/may-change.md) module @ref:[multi node testing](multi-node-testing.md),
|
||||
@ref:[may change](common/may-change.md) module @ref:[multi node testing](multi-node-testing.md),
|
||||
described in that section.
|
||||
|
|
@ -198,4 +198,4 @@ thread. This also means that you shouldn't use them from inside an actor, a futu
|
|||
## Configuration
|
||||
|
||||
There are several configuration properties for the Multi-Node Testing module, please refer
|
||||
to the @ref:[reference configuration](../general/configuration.md#config-akka-multi-node-testkit).
|
||||
to the @ref:[reference configuration](general/configuration.md#config-akka-multi-node-testkit).
|
||||
Loading…
Add table
Add a link
Reference in a new issue