Table of contents

# Building the code from source

## When is it necessary to build from source?

In most cases, you don't need to build from source, and instead you can use a release build downloaded from the Releases page on GitHub. (See the quick start page for more information) You need to build from source in one of the following circumstances:

- To build a version of Shasta for which no release exists. For example, if you want to get a recently added feature that is not available in the most recent release build. For this specific use case, you can also download a Shasta test build form GitHub, as described below.
- To test, develop, or debug Shasta code.
- To port the Shasta build to a different platform.

## How to build from source

### Build platforms

Building from source is currently supported for Ubuntu (20.04 LTS) and macOS (10.15). Porting the build process to other Linux platforms is possible. If you are specifically interested in porting to a different Linux platorm, please file an Issue on GitHub. Even better, submit a Pull Request with the necessary changes.

### Build commands

1. Check out Shasta repository (You need to have `git` installed on your machine)

       git clone https://github.com/chanzuckerberg/shasta.git

2. Install prerequisite packages

       sudo shasta/scripts/InstallPrerequisites-Ubuntu.sh

       # OR

       sudo shasta/scripts/InstallPrerequisites-macOS.sh

3. Build

       mkdir shasta-build
       cd shasta-build
       cmake ../shasta
       make all -j
       make install

   ### Build contents

   The build process described above creates in the `shasta-build` directory a `shasta-install` directory that contains the following:

   - A `bin` directory containing the Shasta executable, named `shasta`, Shasta shared library `shasta.so`, and several scripts.
   - A `conf` directory containing sample config files.
   - A `docs` directory containing this and other documentation.

   ### Building smaller binaries

   If you don't plan to use your build for debugging, you can use command `make install/strip` instead of `make install` as the last step of the build process. This will strip debug symbols from the Shaste executable and shared library, which significantly reduces the size of the build directory.

   ## An alternative to building from source: downloading a test build

   Shasta uses GitHub Actions to perform a test build every time a push to the repository occurs. The main goal of these builds is to test that new code continues to build on all supported platforms, but the builds are accessible to all users for download for 90 days after their creation. The test builds, however, are generally not as reliable as release builds, and can sometimes be non-functional. With this in mind, you can use the folowing steps to download one of these test builds:

   - Make sure to be logged in to GitHub. Any user will work, but GitHub will not allow downloading a test build anonymously.
   - Go to the Commits page of the Shasta repository.
   - Choose a commit that has green checkmark like this ✓. The checkmark indicates that a push occurred at that commit, followed by a successful test build.
   - Click on the green checkmark, then click on one of the Details links that appear in the pop up Window.
   - You are now on the GitHub Actions page for that test build. Click on Artifacts near the top right of the window and select what you want to download. Your browser will then download the file you selected, which will be downloaded zipped. You can use the `gunzip` command, or equivalent, to unzip it. After unzipping it, before you can run it you will also have to set its execute permission bit via `chmod ugo+x filename`.
   Table of contents