5.2 Usage
Reach has a few sub-commands, each with their own options.
However, all commands support the following options:
The environment variable REACH_VERSION signifies what version of Reach to use.
5.2.1 reach compile
You compile your Reach code by executing
$ reach compile SOURCE EXPORT ...
where SOURCE is your source file, and each EXPORT is an exported Reach.App.
If no SOURCE is provided, then index.rsh is used.
If no EXPORT is provided, then main is used.
reach compile supports the following options:
-o/--output ‹OUTPUT› —
Writes compiler output files to ‹OUTPUT›, which defaults to a directory named build in the same directory as SOURCE. --intermediate-files —
Write intermediate files, which may be interesting for debugging compilation failures or using in other contexts.
5.2.2 reach init
You can create template index.rsh and index.mjs files for a simple Reach app by running
$ reach init
5.2.3 reach hashes
You can see which exact versions of Reach Docker images you are using by running
$ reach hashes
This is more precise, but less readable, than reach version, in that each hash refers to the git commit used to build the image.
5.2.4 reach run
You can run a simple Reach application by executing
$ reach run APP
If no APP is provided, index is used.
If APP is a directory, then APP/index is used.
This assumes
Your Reach program is named APP.rsh.
You are using the JavaScript backend and your frontend is named APP.mjs. It also assumes the backend is located at build/APP.main.mjs, and only depends on the Reach standard library.
It then
Compiles your program with Reach.
Builds a Docker image named reachsh/reach-app-APP:latest that depends on the Reach JavaScript standard library.
Executes that image, connected with a private Ethereum devnet.
reach run supports the following options:
The environment variable REACH_CONNECTOR_MODE specifies which context to run in. The default, if this variable is unset or empty, is ETH-test-dockerized-geth. The options are:
ETH-live, which uses a live Ethereum network node, specified by the environment variable ETH_NODE_URI.
ETH-test-dockerized-geth, which uses a Dockerized private Ethereum network.
ETH-test-embedded-ganache, which uses Ganache instead of a private network.
ALGO-test-dockerized-algod, which uses a Dockerized private Algorand network.
FAKE-test-embedded-mock, which uses a simplified mock network.
reach run can be configured via the presence of certain files. In the absence of these files, reach run assumes a default behavior based on reach scaffold.
If a Makefile is present, and if the REACH_CONNECTOR_MODE and RUN_FROM_REACH environment variables are unset or empty, then make run will be invoked, with the RUN_FROM_REACH environment variable set to true.
If a Makefile, Dockerfile, package.json, and docker-compose.yml are all present, then these files will be used. You can call reach scaffold to persist the default versions of these files.
If only some of those files exist, but not all, then reach run will report an error. Please delete them, or add the missing ones.
Furthermore, if all of the scaffolded files are present, then pay special attention to the Makefile that you write, because reach will use it in specific ways. Refer to the Makefile generated by reach scaffold for hints on how to get it right.
Various reach commands may invoke make build, which is assumed to build the Docker image for your app.
reach run ... will invoke make run-target ARGS="...", where "..." is an escaped, space-separated representation of the command-line args to reach run. See examples/argz/Makefile for an example invocation of reach run with command-line arguments.
5.2.5 reach scaffold
You can create template package.json, Dockerfile, docker-compose.yml, and Makefile files for a simple Reach app by running
$ reach scaffold
The files created are the same as those used temporarily by reach run.
5.2.6 reach upgrade
You can upgrade your Reach installation by executing
$ reach upgrade
This may change the default version used by reach commands.
5.2.7 reach update
You can update the Docker images used by your Reach installation by executing
$ reach update
This may change the patch version used by reach commands.
5.2.8 reach version
You can see what version of Reach you have installed by running
$ reach version