Getting Started

Shpadoinkle is built with Nix, but you can build however you like. stack and cabal are supported with or without Nix.

⛄ Snowman

The fastest way to start a new Shpadoinkle project is to build a Snowman. The following command will setup a new "hello world" project for you.

bash <( curl https://gitlab.com/platonic/shpadoinkle/-/raw/master/snowman/generate.sh )

Once you have your new project you can get live reloads with the following command:

nix-shell --command "ghcid --command 'cabal repl' -W -T Main.dev"

This will use nix-shell to setup a development environment for you, then execute ghcid inside the environment to watch your files, and execute Main.dev inside a repl. You can see results at http://localhost:8080. Of course you must have Nix installed for nix-shell to work.

Building from source can take a long time. If you run with nix-build it’s highly recommended you use Cachix.
chan
If you are seeing version errors in your build, or getting something like "attribute X not found", you may need to update your channel. You can manually set the field chan (line 1) in default.nix to either a specific nix-channel version, or a specific hash (the latest hash building Shpadoinkle can be found here). Furthermore, you can control the channel for a build environment with the --argstr chan argument, for instance nix-build --argstr chan "20.03".

Nix

Nix works on all Linux distributions, as well as Darwin-based operating systems such as MacOS. To install Nix run:

curl -L https://nixos.org/nix/install | sh
👏 Follow 👏 Instructions
The install script outputs important instructions you need to follow. Read the output and follow instructions.

Success is indicated by the presence of the Nix toolchain in your terminal…​

nix --version
MacOS
Installing Nix on MacOS should work fine, but if you end up in a sticky situation, this article may help. You can also refer to the official manual for more information about Nix.

Cachix

Some of the work done with Nix includes deviations from the official Nix package set. As such, some dependencies are not cached on https://cache.nixos.org. Building these dependencies from source can be very slow. If you would like to avoid this wait, you can pull from our Cachix cache of pre-built dependencies by executing the following:

nix-env -iA cachix -f https://cachix.org/api/v1/install
cachix use shpadoinkle

After executing the above, subsequent builds will use cached dependencies from shpadoinkle.cachix.org, which are kept up to date with master using GitLab CI.