build/README

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