From 6c03f5c1a69342612de5c9be2da819b86a919c07 Mon Sep 17 00:00:00 2001 From: Scott Lystig Fritchie Date: Wed, 24 Feb 2016 15:08:41 +0900 Subject: [PATCH] Split out docs dev-clone-compile.md and dev-prerequisites.md --- README.md | 9 ++++--- doc/dev-clone-compile.md | 28 +++++++++++++++++++++ doc/dev-prerequisites.md | 18 ++++++++++++++ doc/humming_consensus_demo.md | 46 +++++++++-------------------------- 4 files changed, 63 insertions(+), 38 deletions(-) create mode 100644 doc/dev-clone-compile.md create mode 100644 doc/dev-prerequisites.md diff --git a/README.md b/README.md index 37db1e0..95e24a1 100644 --- a/README.md +++ b/README.md @@ -137,10 +137,13 @@ X. The only known limitations for using R16 are minor type specification difference between R16 and 17, but we strongly suggest continuing development using version 17. -We also assume that you have the standard UNIX/Linux developers -tool chain for C and C++ applications. Specifically, we assume `make` -is available. The utility used to compile the Machi source code, +We also assume that you have the standard UNIX/Linux developer +tool chain for C and C++ applications. Also, we assume +that Git and GNU Make are available. +The utility used to compile the Machi source code, `rebar`, is pre-compiled and included in the repo. +For more details, please see the +[Machi development environment prerequisites doc](./doc/dev-prerequisites.md). Machi has a dependency on the [ELevelDB](https://github.com/basho/eleveldb) library. ELevelDB only diff --git a/doc/dev-clone-compile.md b/doc/dev-clone-compile.md new file mode 100644 index 0000000..9795bb3 --- /dev/null +++ b/doc/dev-clone-compile.md @@ -0,0 +1,28 @@ +# Clone and compile Machi + +Clone the Machi source repo and compile the source and test code. Run +the following commands at your login shell: + + cd /tmp + git clone https://github.com/basho/machi.git + cd machi + git checkout master + make # or 'gmake' if GNU make uses an alternate name + +Then run the unit test suite. This may take up to two minutes or so +to finish. + + make test + +At the end, the test suite should report that all tests passed. + + [... many lines omitted ...] + module 'event_logger' + module 'chain_mgr_legacy' + ======================================================= + All 90 tests passed. + +If you had a test failure, a likely cause may be a limit on the number +of file descriptors available to your user process. (Recent releases +of OS X have a limit of 1024 file descriptors, which may be too slow.) +The output of the `limit -n` will tell you your file descriptor limit. diff --git a/doc/dev-prerequisites.md b/doc/dev-prerequisites.md new file mode 100644 index 0000000..b3987ad --- /dev/null +++ b/doc/dev-prerequisites.md @@ -0,0 +1,18 @@ +## Machi developer environment prerequisites + +1. Machi requires an OS X, FreeBSD, Linux, or Solaris machine is a + standard developer environment for C and C++ applications. +2. You'll need the `git` source management utility. +3. You'll need the Erlang/OTP 17 runtime environment. Please don't + use earlier or later versions until we have a chance to fix the + compilation warnings that versions R16B and 18 will trigger. + +For `git` and the Erlang runtime, please use your OS-specific +package manager to install these. If your package manager doesn't +have Erlang/OTP version 17 available, then we recommend using the +[precompiled packages available at Erlang Solutions](https://www.erlang-solutions.com/resources/download.html). + +Also, please verify that you have enough file descriptors available to +your user processes. The output of `ulimit -n` should report at least +4,000 file descriptors available. If your limit is lower (a frequent +problem for OS X users), please increase it to at least 4,000. diff --git a/doc/humming_consensus_demo.md b/doc/humming_consensus_demo.md index eb66ebe..1f0f3c5 100644 --- a/doc/humming_consensus_demo.md +++ b/doc/humming_consensus_demo.md @@ -7,50 +7,26 @@ # Hand-on experiments with Machi and Humming Consensus - ## Prerequisites -1. Machi requires a OS X, FreeBSD, Linux, or Solaris machine. -2. You'll need the `git` source management utility. -3. You'll need the Erlang/OTP 17 runtime environment. Please don't - use earlier or later versions until we have a chance to fix the - compilation warnings that versions R16B and 18 will trigger. - -For `git` and the Erlang runtime, please use your OS-specific -package manager to install these. If your package manager doesn't -have Erlang/OTP version 17 available, then we recommend using the -[precompiled packages available at Erlang Solutions](https://www.erlang-solutions.com/resources/download.html). - -All of the commands that should be run at your login shell (e.g. Bash, -c-shell) can be cut-and-pasted from this document directly to your -login shell prompt. +Please refer to the +[Machi development environment prerequisites doc](./doc/dev-prerequisites.md) +for Machi developer environment prerequisites. ## Clone and compile the code -Clone the Machi source repo and compile the source and test code. Run -the following commands at your login shell: - - cd /tmp - git clone https://github.com/basho/machi.git - cd machi - git checkout master - make - -Then run the unit test suite. This may take up to two minutes or so -to finish. - - make test - -At the end, the test suite should report that all tests passed. - -If you had a test failure, a likely cause may be a limit on the number -of file descriptors available to your user process. (Recent releases -of OS X have a limit of 1024 file descriptors, which may be too slow.) -The output of the `limit -n` will tell you your file descriptor limit. +Please see the +[Machi 'clone and compile' doc](./doc/dev-clone-compile.md) +for the short list of steps required to fetch the Machi source code +from GitHub and to compile & test Machi. ## Running three Machi instances on a single machine +All of the commands that should be run at your login shell (e.g. Bash, +c-shell) can be cut-and-pasted from this document directly to your +login shell prompt. + Run the following command: make stagedevrel