bootstrap/README.md

   1 # Bootstrapping cabal-install
   2
   3 This utility is only intended for use in building `cabal-install`
   4 on a new platform. If you already have a functional cabal-install, however old, then
   5 please instead run `cabal install cabal-install`.
   6
   7 ## Bootstrapping on Linux
   8
   9 The typical use case is porting to a new Linux architecture. In that case,
  10 a `linux-${GHCVER}.json` file is available in the `bootstrap/` folder:
  11
  12 On a Linux system you are bootstrapping, run
  13
  14     ./bootstrap/bootstrap.py -d ./bootstrap/linux-${GHCVER}.json -w /path/to-ghc
  15
  16 from the top directory of the source checkout.
  17
  18 ### Offline build
  19
  20 For offline builds, you can first run
  21
  22     ./bootstrap/bootstrap.py -d ./bootstrap/linux-${GHCVER}.json -w /path/to-ghc fetch
  23
  24 to fetch tarballs for all the dependencies. These can then be used by a further
  25 bootstrap command by way of the `--bootstrap-sources` argument:
  26
  27     ./bootstrap/bootstrap.py -w /path/to-ghc --bootstrap-sources bootstrap-sources.tar.gz
  28
  29 ## Bootstrapping on other (non-Linux) platforms
  30
  31 You will need to generate a `${PLATFORM}-${GHCVER}.json` file for other platforms and then use it
  32 in the same way as it is shown for Linux above. On a system with functional `cabal-install`, do:
  33
  34 1. Install the same GHC version as you will use to bootstrap on the host system.
  35
  36 2. Build a dependency description file (`$PLATFORM-$GHCVER.json`, e.g. `macosx-8.8.4.json`) by running:
  37
  38    ```sh
  39    cabal build --with-compiler=/path/to/ghc --dry-run cabal-install:exe:cabal
  40    cp dist-newstyle/cache/plan.json bootstrap/$PLATFORM-$GHCVER.plan.json
  41    cd bootstrap
  42    cabal run -v0 cabal-bootstrap-gen -- $PLATFORM-$GHCVER.plan.json | tee $PLATFORM-$GHCVER.json
  43    ```
  44
  45 3. You may need to tweak `bootstrap/$PLATFORM-$GHCVER.json` file manually,
  46      for example, to toggle flags.
  47
  48 There are rules in the top-level `Makefile` for generation of these files.
  49
  50 # Updating Bootstrap Plans
  51
  52 In order to update the bootstrap plans on linux there is the convenient `./generate_bootstrap_plans`
  53 script. You can modify this script with the GHC versions you want to generate the plans for and
  54 then run it to generate the plans.
  55
  56 ```
  57 ./generate_bootstrap_plans
  58 ```
  59