********
Building
********

Building with go build
======================

SCION can be built with ``go build`` without any other system prerequisites.

Please be aware that go build **is not the recommended setup for development** on SCION.
Not all tests and checks can be run in this setup. We use Bazel to orchestrate all of this.
Without running all checks locally, it is likely that there will be frustrating cycles with the CI
system rejecting your changes.
See :doc:`setup` for instructions on how to set up Bazel and the full development environment.

Prerequisites
-------------

#. Clone the SCION repository into your workspace.

   .. code-block:: bash

      git clone https://github.com/scionproto/scion
      cd scion

#. Determine the go version used in the Bazel setup; the ``MODULE.bazel`` file
   specifies this version in the ``go_sdk.download`` clause.

   .. literalinclude:: /../MODULE.bazel
      :start-at: go_sdk.download(
      :end-at: )
      :emphasize-lines: 1

   Building with newer go versions *usually* works.

#. Install go. Either follow `the official instructions <https://go.dev/doc/install>`_
   or check the `Ubuntu specific installation options on the golang wiki <https://github.com/golang/go/wiki/Ubuntu>`_.

Build
-----

* **Build only "distributables"**, without development and testing tools

   .. code-block:: bash

      go build -o bin/ ./{router,control,dispatcher,daemon,scion,scion-pki,gateway}/cmd/...

   .. warning::

      The control service and the daemon need cgo for their sqlite driver
      (``github.com/mattn/go-sqlite3``). Building them requires a C compiler. Without one,
      ``go`` silently sets ``CGO_ENABLED=0``, the build still succeeds, but both binaries
      fail at startup, as soon as they try to open their database.

* **Build all**

   .. code-block:: bash

      go build -o bin/ ./...

Building with Bazel
===================

Please be aware that the following instructions only result in a minimal build
environment. Not all tests and checks can be run in this setup.
See :doc:`setup` for instructions on how to set up Bazel and the full development environment.

Prerequisites
-------------

#. Clone the SCION repository into your workspace.

   .. code-block:: bash

      git clone https://github.com/scionproto/scion
      cd scion

#. Install Bazel: either follow the official instructions at `<https://bazel.build/install>`_, or
   run our helper script:

   .. code-block::

      tools/install_bazel

#. Remove remote cache options from ``.bazelrc``; the default setup is useful to limit Bazel's
   cache size when contributing to SCION, but requires a running docker container acting as the
   "remote" cache service

   .. code-block::

      sed -e '/--remote_cache=/d' -i .bazelrc

   Alternatively, if you have docker installed, you can run ``./scion.sh bazel-remote`` to start
   the cache service.

Build
-----

* **Build only "distributables"**, without development and testing tools

   .. code-block:: sh

      make build                          # or, ...
      bazel build //:scion                # or, ...
      bazel build //control/cmd/control //router/cmd/router <...>

* **Build all**

   .. code-block:: sh

      make build-dev                      # or, ...
      make                                # or, ...
      bazel build //:scion //:scion-ci

* **Build packages for debian (all target architectures)**

  .. code-block:: sh

     make dist-deb                        # or, ...
     bazel build //dist:deb_all

* **Build packages for openwrt (x86_64 only, currently)**

  .. code-block:: sh

     make dist-openwrt                        # or, ...
     bazel build //dist:openwrt_all

Options
-------

* Bundling the management API documentation with the binaries.

   .. code-block:: sh

      bazel build --//:mgmtapi_bundle_doc=true //:scion

glibc dependency
----------------

SCION currently relies on `mattn/go-sqlite3 <https://github.com/mattn/go-sqlite3>`_, a CGO-based
wrapper around SQLite. It is well established, but the CGO dependency complicates the build of
static binaries. In typical glibc-based Linux builds, the resulting executable is often
dynamically linked and may depend on a minimum glibc version. Fully static binaries are still
possible, but require extra tooling.

.. seealso::

   :doc:`setup`
      Instructions for :doc:`installing the full development environment <setup>`.

   :doc:`/manuals/install`
      Information for :doc:`installing SCION from per-built binaries or packages </manuals/install>`.