Skip to content

Latest commit

 

History

History
129 lines (92 loc) · 4.89 KB

build.md

File metadata and controls

129 lines (92 loc) · 4.89 KB

Build soci-snapshotter from source

This document is helpful if you plan to contribute to the project (thanks!) or want to use the latest soci snapshotter/cli in the main branch.

This document includes the following sections:

Dependencies

soci-snapshotter has the following dependencies. Please follow the links or commands to install them on your machine:

We only mention the direct dependencies of the project. Some dependencies may have their own dependencies (e.g., containerd depends on runc/cni). Please refer to their doc for a complete installation guide (mainly containerd).

  • go >= 1.18 - required to build the project; to confirm please check with go version.
  • containerd >= 1.4 - required to run soci-snapshotter; to confirm please check with sudo containerd --version.
  • fuse - used for mounting without root access (sudo yum install fuse).
  • zlib - used for decompression and ztoc creation; soci builds zlib statically into its binaries (sudo yum install zlib-devel zlib-static).
  • gcc - used for compiling SOCI's c code, gzip's zinfo implementation (sudo yum install gcc).
  • flatc - used for compiling ztoc flatbuffer file and generating corresponding go code.

For fuse/zlib/gcc, they can be installed by your Linux package manager (e.g., yum or apt-get).

For flatc, you can download and install a release into your /usr/local (or other $PATH) directory. For example:

wget -c https://github.com/google/flatbuffers/releases/download/v23.3.3/Linux.flatc.binary.g++-10.zip
sudo unzip Linux.flatc.binary.g++-10.zip -d /usr/local
rm Linux.flatc.binary.g++-10.zip

Build soci-snapshotter

First you need git to clone the repository (if you intend to contribute, you can fork the repository and clone your own fork):

git clone https://github.com/awslabs/soci-snapshotter.git
cd soci-snapshotter

soci-snapshotter uses make as the build tool. Assuming you're in the root directory of the repository, you can build soci-snapshotter by:

make

This builds the project binaries into the ./out directory. You can install them to a PATH directory (/usr/local/bin) with:

sudo make install
# check soci can be found in PATH
sudo soci --help

When changing the ztoc's flatbuffer definition, you need to regenerate the generated code package with:

It's rare to make such a change, especially delete a field which is a breaking change and discouraged by flatbuffers.

make flatc

Test soci-snapshotter

We have unit tests and integration tests as part of our automated CI, as well as benchmark tests that can be used to test the performance of soci-snapshotter. You can run these tests using the following Makefile targets:

  • make test: run all unit tests.
  • make integration: run all integration tests.
  • make benchmarks (experimental): run all benchmark tests. This requires some setup and preparation for public images with SOCI index which are used for benchmarking. It is tracked in #245.

To speed up develop-test cycle, you can run individual test(s) by utilizing go test's -run flag. For example, suppose you only want to run a test named TestFooBar, you can:

# 1. if TestFooBar is a unit test
GO_TEST_FLAGS="-run TestFooBar" make test

# 2. if TestFooBar is an integration test
GO_TEST_FLAGS="-run TestFooBar" make integration

(Optional) Contribute your change

If you intend to contribute your change, you need to validate your changes pass all unit/integration tests. (i.e., make test and make integration pass).

Meanwhile, there are a few steps you should follow to ensure your change is ready for review:

  1. If you added any new files, make sure they contain the SOCI license header. We provide a script (./scripts/add-ltag.sh) that can do this.

  2. Make sure your change is well-formatted and you've run gofmt.

  3. Make sure your commit is signed (git commit -s).

  4. As a final step, run make check to verify your change passes these checks.

make check requires some checking tools (golangci, ltag, git-validation). We provide a script (./scripts/install-check-tools.sh) to help install all these checking tools.

Once you pass all the tests and checks. You're ready to make your PR!