Build

You clone the repository and build what the rest of the code is compiled against. At the end of this page the code compiles, and nothing runs yet.

Decide where the checkout goes

Every page after this one names the checkout through one variable, so decide its path now and set it in the shell you are in:

export ZFM_ROOT_DIR=$HOME/projects/zfm    # or wherever you keep projects

To save yourself typing that in every new terminal, make it persistent. In bash:

# persist ZFM_ROOT_DIR
echo "export ZFM_ROOT_DIR=$ZFM_ROOT_DIR" >> ~/.bashrc
# a terminal that is already open has not read it, so in each one:
source ~/.bashrc

Clone it

git clone https://github.com/tmoens/zebrafish-facility-manager "$ZFM_ROOT_DIR"
cd "$ZFM_ROOT_DIR"

Every relative path on the pages after this one is relative to the root of this checkout.

Install the packages

The repository is three npm workspaces: shared, the contract between the client and the server; zf-server; and zf-react-client. One install covers all three:

cd "$ZFM_ROOT_DIR"
npm install

Build the contract

The server and the client import shared as its build, not its source. So it is built before either of them can compile, and built again after every change to it:

cd "$ZFM_ROOT_DIR"
npm run build:libs

A server compiled against a stale shared/dist fails in ways that read as application bugs, which is why the service that runs a facility's server builds this first, every time it starts.

Build the documentation

A facility serves its users a usage guide at /usage-guide/, and on a development machine that guide is built from the checkout. The documentation is built with MkDocs, which is Python, and the toolchain lives in a virtual environment inside the checkout, created once:

cd "$ZFM_ROOT_DIR"
python3 -m venv docs/.venv
docs/.venv/bin/pip install -r docs/requirements.txt

Then build every site:

cd "$ZFM_ROOT_DIR"
docs/build.sh

It builds each site into its own site/ directory, and prints how to read one in a browser.

Am I ready to move on?

cd "$ZFM_ROOT_DIR"
npm run typecheck

Both halves type-check against the contract you just built. A failure here is a failure in the code, not in the machine, and the working tree you cloned is expected to pass.