build/README

   1 Prerequisites
   2 =============
   3
   4 In order to build packages, you will need:
   5
   6 * Docker installed
   7 * permission to run Docker commands
   8 * the `WORKSPACE` environment variable set to the absolute path of an
   9   Arvados Git work tree
  10
  11 Quickstart
  12 ==========
  13
  14 Build and test all the packages for debian10 on your architecture by
  15 running:
  16
  17     ./run-build-test-packages-one-target.sh --arch "$(arch)"
  18
  19 This will build package build and test Docker images for debian10, build all
  20 packages in a build container, then test all packages in a test container.
  21
  22 Use a different distro by adding the `--target TARGET` option.
  23
  24 Limit the build to a single package by adding the `--only-build
  25 PACKAGE_NAME` option. This is helpful when a build is mostly in good shape
  26 and you're tracking down last bugs in one or two packages.
  27
  28 Get more verbose output by adding the `--debug` option.
  29
  30 By default the script avoids rebuilding or retesting packages that it
  31 detects have already been done in past runs. You can force the script to
  32 rebuild or retest package(s) with the `--force-build` and `--force-test`
  33 options, respectively.
  34
  35 Run the script with `--help` for more information about other options.
  36
  37 Scripts in this directory
  38 =========================
  39
  40 run-tests.sh                             Run unit and integration test suite.
  41
  42 run-build-test-packages-one-target.sh    Entry point, wraps
  43                                          run-build-packages-one-target.sh to
  44                                          perform package building and testing
  45                                          inside Docker.
  46
  47 run-build-packages-one-target.sh         Build packages for one target inside Docker.
  48
  49 run-build-packages-all-targets.sh        Run run-build-packages-one-target.sh
  50                                          for every target.
  51
  52 run-build-packages.sh                    Actually build packages.  Intended to run
  53                                          inside Docker container with proper
  54                                          build environment.
  55
  56 run-build-packages-python-and-ruby.sh    Build Python and Ruby packages suitable
  57                                          for upload to PyPi and Rubygems.
  58
  59 run-build-docker-images.sh               Build arvbox Docker images.
  60
  61 run-build-docker-jobs-image.sh           Build arvados/jobs Docker image
  62                                          (uses published debian packages)
  63
  64 build-dev-docker-jobs-image.sh           Build developer arvados/jobs Docker image
  65                                          (uses local git tree)
  66
  67 run-library.sh                           A library of functions shared by the
  68                                          various scripts in this
  69                                          directory.
  70
  71 Adding a new target
  72 ===================
  73
  74 In order to build packages on a new distribution, you MUST:
  75
  76 * Add a rule for `TARGET/generated` to `package-build-dockerfiles/Makefile`.
  77 * Add the new `TARGET/generated` rule to the `all` target in
  78   `package-build-dockerfiles/Makefile`.
  79 * Write `package-build-dockerfiles/TARGET/Dockerfile`.
  80 * Add a rule for `TARGET/generated` to `package-test-dockerfiles/Makefile`.
  81 * Add the new `TARGET/generated` rule to the `all` target in
  82   `package-test-dockerfiles/Makefile`.
  83 * Write `package-test-dockerfiles/TARGET/Dockerfile`.
  84 * Create `package-testing/test-packages-TARGET.sh`, ideally by making it a
  85   symlink to `FORMAT-common-test-packages.sh`.
  86
  87 Of course, any part of our package build or test infrastructure may need to
  88 be updated to accommodate the process for new distributions. If you're
  89 having trouble building lots of packages, consider grepping these build
  90 scripts for the identifier of the closest working target, and see if you may
  91 need to add branches or similar hooks for your target. If you're having
  92 trouble building specific packages, consider doing the same for those
  93 packages' `fpm-info.sh` files.