J.U.S.T. Quickstart Guide for Users

This is a quickstart guide for the intended customers of a just project. This guides will teach you how to:

Use a just project
Identify some common issues and how to collect relevant information to pass on to the developers to help you solve your problems

What is J.U.S.T.

Think of just as a bunch of scripts all wrapped into one command (or script), with the added benefit that it works on Linux, Windows (provided git is installed), and macos without additional dependencies.

The developer will create a number of tasks, and assign them to just targets. For example, if there was a compile target that compiles the code, you run just compile to run that target.

A typical setup is:

To update everything with new code you checked out: just sync
To compile the code: just compile
To run the code: just run

All of these target names can be customized by the developer, but just sync is a very common one to remember. The point of this is to “do all the things you usually forget when you just checked out a new version of the code”, like compiling code or updating a database, etc…

You can always run just help will list all the commands available in your project, with a short description for each command.

Getting started

You start out by downloading your software, this is usually done by git clone. It’s important that the --recursive be included, or else submodules will be missing and you’ll need to initialize them with some more git commands. So start with git clone --recursive {git repo url here}, and cd into the project directory.

Every time you open a new terminal window on your computer, you will need to start bash, change directory (cd) into the project directory and run source setup.env (. setup.env is a shortened version of the same command) from your project folder. This will setup just (add just to your PATH) so that you can run just by typing just, instead of ./external/vsi_common/linux/just, which is a bit wordy and inconvenient.

Start off by running just help, to see the list of all advertised just commands. There are a few commands that are in every just project:

-h/--help/help - Print out the help
--dryrun/-n - Dry run mode. Some commands can be run in dry run mode, which means they are printed out instead of run. This can be useful for debugging purposes. You have to add this flag before the target name, not after
--version - Print out the version of just you currently using
--wrap - Commands in just run in their own environment with dozens of environment variables exported, making it extremely complicated to run some commands outside of just. just --wrap allows you to run any arbitrary command in the just environment, (it wraps the command in just). For example, if you need to start a database that uses environment variables to start correctly, you can run just --wrap /opt/db/database_program --db /data/foo.dat
--run - --run is similar to --wrap, but runs much deeper in the mechanics of just in a place called Justfile caseify. This is more for debugging, and users are unlikely to use this, unless instructed to do so.
--separator - When you are chaining multiple commands together, you can use -- (the default JUST_SEPARATOR) to separate multiple commands. However if you need to use -- for your own commands, --separator lets you tell just to use something else for it’s separator, (e.g. --separator @@)
--new - For developer to create a new_just project
--tab - For future feature
--latest - For future feature

Commands and subcommands

You may notice the help is split into two sections, “commands” and “subcommands”. A command may or may not take arguments (like a file name), depending on how the developer writes that target. But sometimes we group together multiple word commands, and we call those special arguments “subcommands”.

Subcommands
-----------
test
    int               Run integration tests

int is a subcommand of test, and can be run by saying just test int

Command chaining

Multiple commands can be run in one just command. Imagine the following just help output:

List of possible just commands:
-----------------------------------
compile   Compiles project, takes no arguments
print     Echos out all the remaining arguments
process   Processes the first argument

Subcommands
-----------
build
    docker        Builds docker images
    singularity   Builds singularity images

You can combine compile and process in one just call: just compile process data.json

You can also combine subcommands without having to repeat the command name. In other words: just build docker build singularity can be shorten to just build docker singularity

Targets like print will consume all the arguments, but you can break it with a JUST_SEPARATOR (-- by default): just compile print Compile is done -- process data.json

`local.env`

When you clone a project, all the default settings are loaded into the just project. In order to customize the install for your computer, you can edit a local.env (that is auto generated the first time you run just). You are encouraged to customize every setting you need in your :file:local.env, however this file will never be committed to the repository, and is only for your local install. For example, if you wanted to change a variable called PROJECTX_DATABASE_DIR, you would add that to your local.env:

local.env

PROJECTX_DATABASE_DIR=/data3/x/run1

You can do anything you want in bash in that file, but is encouraged to:

Not do anything that takes a long time to run. A second time delay means you have to wait a second every time you run just
Don’t print out anything to the screen (except for debugging), it will just clutter the screen

Troubleshooting

I cloned the repo, and when I source setup.env, all I see is:
$ . setup.env bash: ./external/vsi_common/env.bsh: No such file or directory
- This probably means you did not successfully clone the submodules of the repository. Check that you have the vsi_common submodule, and try again after fixing

I ran a command, and saw a lot of output ending with a weird stack trace:

$ just do something

Call stack
----------
833 defaultify  /opt/projects/just_a_project/external/vsi_common/linux/just_functions.bsh
102 caseify     Justfile
1034 _justify   /opt/projects/just_a_project/external/vsi_common/linux/just_functions.bsh
980 justify     /opt/projects/just_a_project/external/vsi_common/linux/just_functions.bsh
264 main        /opt/projects/just_a_project/external/vsi_common/linux/just

/opt/projects/just_a_project/external/vsi_common/linux/just_functions.bsh: line 833: Returned 1

This is a just stack trace, and can be very useful to a developer when reporting an error. There may even be multiple stacks for one error, be sure to copy them all

What do you mean you don’t understand?
$ just foo bar I don't understand: foo
- When just can’t find a target, this is the generic error message you get. Either bar is not a subcommand of foo, or foo isn’t a command at all.
1: unbound variable A number is unbound, what?
$ just docker clean /opt/projects/just_a_project/external/vsi_common/linux/just_docker_functions.bsh: line 119: 1: unbound variable
- Arguments are assigned numbers as the variable names. This means it was expecting an argument, and didn’t get one. Typically 1 means the first argument, 2 means the second argument. However, bash can shift arguments around and a number could be any argument after that number. Either way, it was expecting an argument, and didn’t get one. If this was not clear by the help text, please let your developer know this so they can correct that.
unbound variable
$ just error Justfile: line 125: PROJECTX_DATABASE_DIR: unbound variable
- The variable PROJECTX_DATABASE_DIR was not set and had no default value. Either the README should have told you to set a value in your local.env, or the developer made a mistake and needs to be notified so they can fix it. If you know what the value should be, you are free to just update local.env. But if this is erroneous behavior, then it should be reported.