github.com/coreos/rocket@v1.30.1-0.20200224141603-171c416fac02/Documentation/build-configure.md (about)

     1  # Build Configuration
     2  
     3  ## Overview
     4  
     5  This file describes all the parameters of the configure script and their possible uses.
     6  For a quick help of available parameters, run `./configure --help`.
     7  
     8  ## Parameters for building stage1 flavors
     9  
    10  #### `--with-stage1-flavors`
    11  
    12  This parameter takes a comma-separated list of all the flavors that the build system should assemble.
    13  Depending on a default stage1 image setup, this list is by default either empty or set to `coreos,kvm,fly` for, respectively, detailed setup and flavor setup.
    14  Note that specifying this parameter does not necessarily mean that rkt will use them in the end.
    15  Available flavors are:
    16  
    17  - `coreos` - it takes systemd and bash from a CoreOS Container Linux PXE image; uses systemd-nspawn
    18  - `kvm` - it takes systemd, bash and other binaries from a Container Linux PXE image; uses lkvm or qemu
    19  - `src` - it builds systemd, takes bash from the host at build time; uses built systemd-nspawn
    20  - `host` - it takes systemd and bash from host at runtime; uses systemd-nspawn from the host
    21  - `fly` - chroot-only approach for single-application minimal isolation containers; native Go implementation
    22  
    23  The `host` flavor is probably the best suited flavor for distributions that have strict rules about software sources.
    24  
    25  #### `--with-stage1-flavors-version-override`
    26  
    27  This parameter takes a version number to become the version of all the built stage1 flavors.
    28  Normally, without this parameter, the images have the same version as rkt itself.
    29  This parameter may be useful for distributions that often provide patched versions of upstream software without changing major/minor/patch version number, but instead add a numeric suffix.
    30  An example usage could be passing `--with-stage1-flavors-version-override=0.12.0-2`, so the new image will have a version `0.12.0-2` instead of `0.12.0`.
    31  This parameter also affects the default stage1 image version in flavor setup.
    32  
    33  ## Parameters for setting up default stage1 image
    34  
    35  The parameters described below affect the handling of rkt's default stage1 image.
    36  rkt first tries to find the stage1 image in the store by using the default stage1 image name and version.
    37  If this fails, rkt will try to fetch the image into the store from the default stage1 image location.
    38  
    39  There are two mutually exclusive ways to specify a default stage1 image name and version:
    40  
    41  - flavor setup
    42  - detailed setup
    43  
    44  ### Flavor setup
    45  
    46  Flavor setup has only one parameter.
    47  This kind of setup is rather a convenience wrapper around the detailed setup.
    48  
    49  #### `--with-stage1-default-flavor`
    50  
    51  It takes a name of the flavor of the stage1 image we build and, based on that, it sets up the default stage1 image name and version.
    52  Default stage1 image in this case is often something like coreos.com/rkt/stage1-<name of the flavor>.
    53  Default stage1 version is usually just rkt version, unless it is overridden with `--with-stage1-flavors-version-override`.
    54  This is the default setup if neither flavor nor detailed setup are used.
    55  The default stage1 image flavor is the first flavor on the list in `--with-stage1-flavors`.
    56  
    57  ### Detailed setup
    58  
    59  Detailed setup has two parameters, both must be provided.
    60  This kind of setup could be used to make some 3rd party stage1 implementation the default stage1 image used by rkt.
    61  
    62  #### `--with-stage1-default-name`
    63  
    64  This parameter tells what is the name of the default stage1 image.
    65  
    66  #### `--with-stage1-default-version`
    67  
    68  This parameter tells what is the version of the default stage1 image.
    69  
    70  ### Location of the default stage1 image
    71  
    72  #### `--with-stage1-default-location`
    73  
    74  This parameter tells rkt where to find the default stage1 image if it is not found in the store.
    75  For the detailed setup, the default value of this parameter is empty, so if it is not provided, you may be forced to inform rkt about the location of the stage1 image at runtime.
    76  For the flavor setup, the default value is also empty, which tells rkt to look for the image in the directory the rkt binary is located, unless it is overridden at runtime.
    77  Normally, this parameter should be some URL, with a scheme or an absolute path.
    78  
    79  #### `--with-stage1-default-images-directory`
    80  
    81  This parameter tells rkt where the directory which contains all the stage1 images is located.
    82  The value should be an absolute path.
    83  In this directory, all the built flavors of stage1 images should be installed.
    84  The `--stage1-from-dir` rkt flag will look for images in this directory.
    85  The default value of this parameter is `<libdir>/rkt/stage1-images`, where `<libdir>` is a distribution-specific place for storing arch-dependent files.
    86  
    87  ## Flavor-specific parameters
    88  
    89  There are some additional parameters for some flavors.
    90  Usually they do not need to be modified, default values are sane.
    91  
    92  ### `src` flavor
    93  
    94  `src` flavor provides parameters for specifying some `git`-specific details of the systemd repository.
    95  
    96  #### `--with-stage1-systemd-src`
    97  
    98  This parameter takes a URL to a `systemd` git repository.
    99  The default is `https://github.com/systemd/systemd.git`.
   100  You may want to change it to point the build system to use some local repository.
   101  
   102  #### `--with-stage1-systemd-version`
   103  
   104  This parameter specifies the systemd version to be built.
   105  Version names are usually in form of `v<number>`, where number is a systemd version.
   106  The default is `v999`.
   107  
   108  #### `--with-stage1-systemd-revision`
   109  
   110  This parameter takes either a tag name or a branch name.
   111  You can use branch name `master` to test the bleeding edge version of systemd or any working branch, or tag name.
   112  Since arbitrary branch names do not imply which systemd version is being built, the actual systemd version
   113  is specified using `--with-stage1-systemd-version`.
   114  The default is `master`.
   115  
   116  ### `coreos` and `kvm` flavor
   117  
   118  `coreos` and `kvm` flavors provide parameters related to CoreOS Container Linux PXE image.
   119  
   120  #### `--with-coreos-local-pxe-image-path`
   121  
   122  This parameter is used to point the build system to a local Container Linux PXE image.
   123  This can be helpful for some packagers, where downloading anything over the network is a no-no.
   124  The parameter takes either relative or absolute paths.
   125  The default value is empty, so the image will be downloaded over the network.
   126  If this parameter is specified, then also `--with-coreos-local-pxe-image-systemd-version` must be specified too.
   127  
   128  #### `--with-coreos-local-pxe-image-systemd-version`
   129  
   130  The build system has no reliable way to deduce automatically what version of systemd the Container Linux PXE image contains, so it needs some help.
   131  This parameters tells the build systemd what is the version of systemd in the local PXE image.
   132  The value should be like tag name in systemd git repository, that is - `v<number>`, like `v229`.
   133  If this parameter is specified, then also `--with-coreos-local-pxe-image-path` must be specified too.
   134  
   135  ## Testing
   136  
   137  There is only one flag for testing - to enable functional testing.
   138  
   139  #### `--enable-functional-tests`
   140  
   141  Functional tests are disabled by default.
   142  There are some requirements to be fulfilled to be able to run them.
   143  The tests are runnable only in Linux.
   144  The tests must be run as root, so the build system uses sudo to achieve that.
   145  Note that using sudo may kill the non-interactivity of the build system, so make sure that if you use it in some CI, then CI user is a sudoer and does not need a password.
   146  Also, when trying to run functional tests with the host flavor of the stage1 image, the host must be managed by systemd of at least version v220.
   147  If any of the requirements above are not met and the value of the parameter is yes then configure will bail out.
   148  This may not be ideal in CI environment, so there is a third possible value of this parameter - "auto".
   149  "auto" will enable functional tests if all the requirements are met.
   150  Otherwise, it will disable them without any errors.
   151  
   152  ## Security
   153  
   154  These flags are related to security.
   155  
   156  #### `--enable-tpm`
   157  
   158  This option to enable [logging to the TPM][rkt-tpm] is set by default. For logging to work, [TrouSerS][trousers] is required. Set this option to `auto` to conditionally enable TPM features based on build support.
   159  
   160  #### `--enable-insecure-go`
   161  
   162  This option to allow building rkt with go having known security issues is unset by default. Use it with caution.
   163  
   164  ## Development
   165  
   166  #### `--enable-incremental-build`
   167  
   168  This option enables incremental compilation. This is useful for local development.
   169  In contrast to a release build this option enables `go install` vs `go build`
   170  which decreases incremental compilation time.
   171  Note that this option is not supported in cross-compile builds.
   172  For this reason the incremental build option must not be used for release builds.
   173  
   174  [rkt-tpm]: devel/tpm.md
   175  [trousers]: http://trousers.sourceforge.net/