Skip to content

DEVELOPER.md

Latest commit

 

History

History
228 lines (171 loc) · 8.49 KB

DEVELOPER.md

File metadata and controls

228 lines (171 loc) · 8.49 KB
Raw

Building and running

Note Successfully building from source requires attending to all of the prerequisites shown below. When users experience errors, it is typically related to failure to assure all prerequisites are met. Work is in progress to improve this experience.

Prerequisites

Compile all projects and generate executable

Building some of the subprojects is just a matter of sbt compile.

# Compile all projects
sbt:rchain> compile

# Compile all projects with tests
sbt:rchain> test:compile

# Create executable
# path: ./node/target/universal/stage/bin/rnode
sbt:rchain> stage

# Delete all files created in build process
sbt:rchain> clean

Default memory limits may not be sufficient so additional options for sbt can be specified. They can be added to .bashrc file.

Increase heap memory and thread stack size. Disable supershell if empty lines are printed in sbt output.

export SBT_OPTS="-Xmx4g -Xss2m -Dsbt.supershell=false"

IDE support

IntelliJ IDEA

For working with the project in IntelliJ Idea IDE it's enough to compile the project in terminal and open it in IDE which will start sbt import.

If multiple versions of the JVM are installed on the system, manual selection of the default SDK may be required.

image

VSCode

With Scala (Metals) extension and bloop compiler, VSCode editor can also be used to work on the project.

Information for developers

Assure prerequisites shown above are met.

Developer Quick-Start

When working in a single project, scope all sbt commands to that project. The most effective way is to maintain a running sbt instance, invoked from the project root:

$ sbt
[info] Loading settings from plugins.sbt ...
[info] Loading global plugins from /home/kirkwood/.sbt/1.0/plugins
[info] Loading settings from plugins.sbt,protoc.sbt ...
[info] Loading project definition from /home/kirkwood/src/rchain/project
[info] Loading settings from build.sbt ...
[info] Set current project to rchain (in build file:/home/kirkwood/src/rchain/)
[info] sbt server started at local:///home/kirkwood/.sbt/1.0/server/e6a65c30ec6e52272d3a/sock
sbt:rchain> project rspace
[info] Set current project to rspace (in build file:/home/kirkwood/src/rchain/)
sbt:rspace> compile
[... compiling rspace ...]

but single-line commands work, too:

$ sbt "project rspace" clean compile test

or

$ sbt rspace/clean rspace/compile rspace/test

Building

The build is organized into several, mostly autonomous projects. These projects may be built (and used!) on their own, or they may be combined together to form the full node package. The build process in any case is contained in and controlled by a single, top-level build.sbt file. This process is able to produce several different kinds of artifacts, including JAR files (for Scala) and Docker images.

The most up-to-date code is found in the main branch. This brilliant, cutting-edge source is periodically merged into main, which branch should represent a more stable, tested version.

Packaging

To publish a docker image to your local repo run:

$ sbt node/docker:publishLocal
[... output snipped ...]
[info] Step 8/8 : ENTRYPOINT ["\/bin\/main.sh"]
[info]  ---> Running in 2ac7f835192d
[info] Removing intermediate container 2ac7f835192d
[info]  ---> 5e79e6d92528
[info] Successfully built 5e79e6d92528
[info] Tagging image 5e79e6d92528 with name: coop.rchain/rnode
[success] Total time: 35 s, completed May 24, 2018 10:19:14 AM

Check the local docker repo:

$ docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
coop.rchain/rnode   latest              5e79e6d92528        7 minutes ago       143MB
<none>              <none>              e9b49f497dd7        47 hours ago        143MB
openjdk             8u151-jre-alpine    b1bd879ca9b3        4 months ago        82MB

To deploy a tarball run:

$ sbt node/universal:packageZipTarball

The tarball can be found in directory node/target/universal/

Running

To run rnode locally from within sbt use the revolver plugin. It will start the app in a forked JVM.

$ sbt
sbt:rchain> project node
sbt:node> reStart run -s

Now after you've done some local changes and want to test them, simply run the last command reStart run -s again. It will kill the running app and start a new instance containing latest changes in a completely new forked JVM.

Running tests in IntelliJ

For tests of the Rholang module, make sure you've got the following JVM options set in your Run Configuration: -Xss240k -XX:MaxJavaStackTraceDepth=10000 -Xmx128m

Otherwise the StackSafetySpec is going to be veeery slow and will most likely fail due to timeouts.

You can make the above options default by editing the ScalaTest Template in Run > Edit configurations > Templates.

Description of subprojects

More info about subprojects can be found in the Wiki.

Communication

The comm subproject contains code for network related operations for RChain.

Rholang

The rholang subproject contains compiler related code for the Rholang language.

Rspace

The rspace subproject contains code related to the key-value storage of the RChain blockchain.