diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index c4ee26916d..0f1dcd4ee8 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -55,32 +55,9 @@ jobs: run: | cabal --version ghc --version - cabal update - cabal install -w ghc-9.0.1 --install-method=copy --overwrite-policy=always - - build-linux-stack: - runs-on: ubuntu-20.04 - - steps: - - uses: actions/checkout@v2 - - - name: Install dependencies - run: | - sudo apt-get update - sudo apt-get install -y haskell-stack - - - uses: actions/cache@v2 - name: Cache ~/.stack and .stack-work - with: - path: | - ~/.stack - .stack-work - key: ${{ runner.os }}-stack - - - name: Build Futhark - run: | - stack setup - stack install + make configure + make build + make install build-mac-cabal: runs-on: macos-latest @@ -100,7 +77,7 @@ jobs: ~/.cabal/packages ~/.cabal/store dist-newstyle - key: ${{ runner.os }}-cabal + key: ${{ runner.os }}-cabal-${{ hashFiles('src', 'futhark.cabal') }} - name: Build run: | @@ -139,10 +116,10 @@ jobs: ~/.cabal/packages ~/.cabal/store dist-newstyle - key: ${{ runner.os }}-${{ hashFiles('nix/sources.json') }}-style + key: ${{ runner.os }}-${{ hashFiles('nix/sources.json', 'src') }}-style - name: Style check - run: nix-shell --pure --run "tools/style-check.sh src unittests" + run: nix-shell --pure --run "make check" build-docs: runs-on: ubuntu-20.04 @@ -160,12 +137,12 @@ jobs: ~/.cabal/packages ~/.cabal/store dist-newstyle - key: ${{ runner.os }}-${{ hashFiles('nix/sources.json') }}-haddock + key: ${{ runner.os }}-${{ hashFiles('nix/sources.json', 'src') }}-haddock - name: Run haddock run: | - nix-shell --pure --run "cabal update" - nix-shell --pure --run "cabal haddock" + nix-shell --pure --run "make configure" + nix-shell --pure --run "make docs" test-interpreter: runs-on: ubuntu-20.04 diff --git a/HACKING.md b/HACKING.md index aefedbb5cd..302e478516 100644 --- a/HACKING.md +++ b/HACKING.md @@ -2,57 +2,43 @@ The Futhark compiler is a significant body of code with a not entirely straightforward design. The main source of documentation is the -Haddock comments in the source code itself. You can generate -hyperlinked reference documentation by running `cabal haddock` (see -below). +Haddock comments in the source code itself. You can generate +hyperlinked reference documentation by running `make docs` (see +below). To build the compiler, you need a recent version of +[GHC](http://ghc.haskell.org/) If you [install +Nix](https://nixos.org/download.html#download-nix) then you can run +`nix-shell` to get a shell environment in which all necessary tools +are installed. -If you [install Nix](https://nixos.org/download.html#download-nix) -then you can run `nix-shell` to get a shell environment in which all -necessary tooling is installed. - -* [Reference documentation for the latest - release](http://hackage.haskell.org/package/futhark) - -* [Haskell style guide](STYLE.md) +Make sure to see the [Haskell style guide](STYLE.md). If you feel that the documentation is incomplete, or something lacks an explanation, then feel free to [report it as an issue](https://github.com/diku-dk/futhark/issues). Documentation bugs are bugs too. -## Compiling with Cabal +## Building -The Futhark compiler is often build using Cabal, the Haskell build -tool. You need to install an appropriate version of GHC yourself, -e.g. with [ghcup](https://www.haskell.org/ghcup/) or by using -`nix-shell`. The following commands are then interesting: +We include a `Makefile` with the following targets. -* `cabal build`: build the Futhark compiler. +* `make build` (or just `make`) builds the compiler. -* `cabal run futhark -- args...`: run the Futhark compiler with the - provided options, first (re)compiling it if necessary. +* `make install` builds the compiler and copies the resulting binaries + to `$HOME/.local/bin`, or `$PREFIX/bin` if the `PREFIX` environment + variable is set. -* `cabal haddock --enable-documentation`: generate hyperlinked documentation. +* `make docs` builds internal compiler documentation. For the user + documentation, see the `docs/` subdirectory. -## Compiling with Stack +* `make check` style-checks all code. Requires [GNU + Parallel](https://www.gnu.org/software/parallel/). -The Futhark compiler is somtimes built using -[Stack](https://docs.haskellstack.org/en/stable/README/). It's a good -idea to familiarise yourself with how it works. As a starting point, -here are a few hints: +* `make check-commit` style-checks all code staged for a commit. + Requires [GNU Parallel](https://www.gnu.org/software/parallel/). -- When testing, pass `--fast` to `stack` to disable the GHC - optimiser. This speeds up builds considerably (although it still - takes a while). The resulting Futhark compiler will run slower, - but it is not something you will notice for small test programs. -- When debugging, pass `--profile` to `stack`. This will build the - Futhark compiler with debugging information (not just profiling). - In particular, hard crashes will print a stack trace. You can also - get actual profiling information by passing `+RTS -pprof-all -RTS` - to the Futhark compiler. This asks the Haskell runtime to print - profiling information to a file. For more information, see the - [Profiling](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html) - chapter in the GHC User Guide. +You can also use `cabal` directly if you are familiar with it. In +particular, `cabal run futhark -- args...` is useful for running the +Futhark compiler with the provided args. ## Debugging Internal Type Errors @@ -100,11 +86,12 @@ specific passes. You may wish to set the environment variable `FUTHARK_COMPILER_DEBUGGING=1`. This has the following effects: -- The frontend prints internal names. (This may affect code - generation in some cases, so turn it off when actually - generating code.) -- Tools that talk to server-mode executables will print the messages - sent back and worth on the standard error stream. + +- The frontend prints internal names. (This may affect code + generation in some cases, so turn it off when actually + generating code.) +- Tools that talk to server-mode executables will print the messages + sent back and worth on the standard error stream. ## Running compiler pipelines diff --git a/Makefile b/Makefile new file mode 100644 index 0000000000..0b32c15a69 --- /dev/null +++ b/Makefile @@ -0,0 +1,32 @@ +# This Makefile mostly serves to abbreviate build commands that are +# unnecessarily obtuse or longwinded. It depends on the underlying +# build tool (cabal) to actually do anything incrementally. +# Configuration is mostly read from cabal.project. + +PREFIX?=$(HOME)/.local + +.PHONY: build install docs clean + +all: build + +configure: + cabal update + cabal configure + +build: + cabal build + +install: build + install -D $$(cabal -v0 list-bin futhark:futhark) $(PREFIX)/bin + +docs: + cabal haddock --enable-documentation + +check: + tools/style-check.sh src unittests + +check-commit: + tools/style-check.sh $$(git diff-index --cached --name-status HEAD | awk '$$1 != "D" && /\\.l?hsc?$$/ { print $$2 }') + +clean: + cabal clean diff --git a/README.md b/README.md index 06c8d64644..32e15b0c45 100644 --- a/README.md +++ b/README.md @@ -33,10 +33,8 @@ For more information, see: Hacking ======= -We welcome all contributions! - Issues tagged with [good first issue](https://github.com/diku-dk/futhark/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) do not require deep knowledge of the code base. -For contributing code, see also [the style guide](STYLE.md). +For contributing code, see [the hacking instructions](HACKING.md). diff --git a/docs/installation.rst b/docs/installation.rst index a75afd1e1a..c78c2adc8d 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -36,14 +36,13 @@ See the documentation for the respective compiler backends. Compiling from source --------------------- -The recommended way to compile Futhark is with the `Haskell Tool -Stack`_, which handles dependencies and compilation of the Futhark -compiler. You will therefore need to install the ``stack`` tool. -Fortunately, the ``stack`` developers provide ample documentation -about `installing Stack`_ on a multitude of operating systems. If -you're lucky, it may even be in your local package repository. - -You can either retrieve a `source release tarball +To compile Futhark you must first install an appropriate version of +GHC, either with [ghcup](https://www.haskell.org/ghcup/) or a package +manager. Any version since GHC 8.10 should work. You also need the +``cabal`` command line program, which ghcup will install for you as +well. + +You then either retrieve a `source release tarball `_ or perform a checkout of our Git repository:: @@ -53,48 +52,27 @@ This will create a directory ``futhark``, which you must enter:: $ cd futhark -To get all the prerequisites for building the Futhark compiler -(including, if necessary, the appropriate version of the Haskell -compiler), run:: +First you must run the following command to download metadata about +Futhark's dependencies:: - $ stack setup + $ make configure -Note that this will not install anything system-wide and will have no -effect outside the Futhark build directory. Now you can run the -following command to build the Futhark compiler, including all -dependencies:: +To build the Futhark compiler and all of its dependencies, run:: - $ stack build + $ make build -The Futhark compiler and its tools will now be built. This step -typically requires at least 8GiB of memory. You may be able to build -it on a smaller machine by adding the ``--fast`` option, although the -resulting Futhark compiler binary will run slower. +This step typically requires at least 8GiB of memory. This will +create files in your ``~/.cabal`` and ``~/.ghc`` directories. After building, you can copy the binaries to your ``$HOME/.local/bin`` directory by running:: - $ stack install - -Note that this does not install the Futhark manual pages. - -Compiling with ``cabal`` -~~~~~~~~~~~~~~~~~~~~~~~~ - -You can also compile Futhark with ``cabal``. If so, you must install -an appropriate version of GHC (usually the newest) and ``cabal`` -yourself, for example through your favourite package manager. On -Linux, you can always use `ghcup -`_. Then clone the -repository as listed above and run:: - - $ cabal update - $ cabal build - -To install the Futhark binaries to a specific location, for example -``$HOME/.local/bin``, run:: + $ make install - $ cabal install --install-method=copy --overwrite-policy=always --installdir=$HOME/.local/bin/ +You can set the ``PREFIX`` environment variable to indicate a +different installation path. Note that this does not install the +Futhark manual pages. You can delete ``~/.cabal`` and ``~/.ghc`` +after this if you wish - the ``futhark`` binary will still work. Installing from a precompiled snapshot -------------------------------------- diff --git a/tools/git-hooks/pre-commit b/tools/git-hooks/pre-commit index f6f8160df5..ce00b73d7e 100755 --- a/tools/git-hooks/pre-commit +++ b/tools/git-hooks/pre-commit @@ -27,12 +27,5 @@ if git diff-index --cached --check HEAD | egrep -v '^[+-]'; then fail fi -# Run hlint on changed (but not deleted) Haskell source files. -files=$(git diff-index --cached --name-status HEAD | awk '$1 != "D" && /\.l?hsc?$/ { print $2 }') -if [ "$files" ]; then - tools/style-check.sh $files || exit 1 -fi - -if ! stack build; then - fail -fi +make check-commit +make build diff --git a/tools/style-check.sh b/tools/style-check.sh index 2188a0e759..b34b9c9b70 100755 --- a/tools/style-check.sh +++ b/tools/style-check.sh @@ -6,6 +6,8 @@ set -e set -o pipefail check="$(dirname $0)"/style-check-file.sh -# Running a style checker will not contribute to a scientific -# publication. -find "$@" -type f | parallel --will-cite "$check" +if [ "$@" ]; then + # Running a style checker will not contribute to a scientific + # publication. + find "$@" -type f | parallel --will-cite "$check" +fi