Skip to content

Latest commit

 

History

History
211 lines (157 loc) · 5.54 KB

make.md

File metadata and controls

211 lines (157 loc) · 5.54 KB
Raw

Hadrian for Make users

This is a cheatsheet-style document meant to succinctly show how to use Hadrian for any GHC developer familiar with the Make build system, by showing the Make command(s) to achieve some goal and then the Hadrian equivalent. If you are looking for a more verbose and comprehensive document, you should head to Hadrian's README.

tl;dr

For GHC hackers already used to the Make build system, here is what you need to know:

  • You still need to boot and configure yourself.
  • Use hadrian/build.{sh, bat} instead of make. It supports -j. This build script will from now on be referred to as simply build.
  • Build products are not in inplace anymore, but _build by default. Your stage 2 GHC would then be at _build/stage1/bin/ghc (because it's built by the stage 1 compiler).
  • The build root is configurable with --build-root or -o.
  • You can pick the build flavour with --flavour=X where X is perf, prof, etc.
  • You can run tests with build test, and specific ones by adding --only="T12345 T11223" for example.
  • GHCs built by Hadrian are relocatable on Windows, Linux, OS X and FreeBSD. This means you can move the <build root>/stage1/{lib, bin} directories around and GHC will still happily work, as long as both directories stay next to each other.

Of particular interest is the --build-root/-o option, which is often useful to work on different things or build GHC in different ways, from the same directory/GHC checkout, without having to sacrifice the build artifacts every time you fire up a build. This is not possible with the Make build system.

Equivalent commands

  • Building a complete stage 2 compiler with its libraries, default flavour

    # Make
make

# Hadrian
build

  • Building with many cores

    # Make
make -j8

# Hadrian
build -j8

  • Building a stage 1 or 2 GHC executable

    # Make
make inplace/bin/ghc-stage1
make inplace/bin/ghc-stage2

# Hadrian
build stage1:exe:ghc-bin    # using the simple target name
build _build/stage0/bin/ghc # OR using the actual path

build stage2:exe:ghc-bin    # simple target
build _build/stage1/bin/ghc # OR actual path

  • Building and registering a library with the stage 2 compiler

    # Make
make inplace/lib/package.conf.d/text-1.2.3.0.conf

# Hadrian
build stage2:lib:text                                    # simple target
build _build/stage1/lib/package.conf.d/text-1.2.3.0.conf # OR actual path

  • Building with a particular flavour (e.g quickest)

    # Make
echo "BuildFlavour=quickest" >> mk/build.mk
make

# Hadrian
build --flavour=quickest

    See flavours documentation for info on flavours.

  • Freezing the stage 1 GHC compiler

    # Make
echo "stage=2" >> mk/build.mk
make

# Hadrian
build --freeze1

  • Running the testsuite

    # Make
make test                             # (1)
make test TEST=plugins01              # (2)
make test TEST="plugins01 plugins02"  # (3)
make accept                           # (4)
PLATFORM=YES OS=YES make accept       # (5)


# Hadrian
build test # equivalent to (1)

build test --only=plugins01 # equivalent to (2)
TEST=plugins01 build test   # equivalent to (2)

build test --only="plugins01 plugins02"    # equivalent to (3)
TEST="plugins01 plugins02" build test      # equivalent to (3)
TEST=plugins01 build test --only=plugins02 # equivalent to (3)

build test -a            # equivalent to (4)
build test --test-accept # equivalent to (4)

PLATFORM=YES OS=YES build test -a            # equivalent to (5)
PLATFORM=YES OS=YES build test --test-accept # equivalent to (5)

    As illustrated in the examples above, you can use the TEST environment variable, the --only=... flag or even both to restrict your testsuite run to some (usually small) subset of the testsuite.

    See the docs for the test rules if you want to know about all the options that hadrian supports and what they correspond to in the Make build system.

  • Generate the settings file to be used for stage 1/2 GHC

    # Make
make inplace/lib/settings

# Hadrian
build _build/stage0/lib/settings
build _build/stage1/lib/settings

  • Build a static library for base with the stage 1 compiler

    # Make
make libraries/base/dist-install/build/libHSbase-4.12.0.0.a

# Hadrian
build _build/stage1/libraries/base/build/libHSbase-4.12.0.0.a

  • Generate haddocks, user guide, etc

    # Make
make docs

# Hadrian
build docs

  • Build documentation, but without haddocks (resp. without HTML or PDF manuals)

    # Make
echo 'HADDOCKS_DOCS = NO' > mk/build.mk
# For HTML manuals: BUILD_SPHINX_HTML = NO
# For PDF manuals: BUILD_SPHINX_PDF = NO
make

# Hadrian
build docs --docs=no-haddocks
# Append --docs=no-sphinx-pdfs, --docs=no-sphinx-html or
# --docs=no-sphinx-man (or --docs=no-sphinx to encompass them all)
# to further reduce or even completely disable documentation targets.

  • Running nofib

    # Make
cd nofib; make clean; make boot; make 2>&1 | tee nofib-log

# Hadrian
build nofib # builds the compiler and everything we need if necessary, too

  • make FAST=YES

    Partially supported in hadrian with the --skip-depends argument. Since hadrian is not directory aware some of the features of FAST=YES are not replicated.

    # Make
make FAST=YES

# Hadrian
build --skip-depends