NixTalk

Overview

This repository contains the source code for a web presentation on functional programming using Yesod and Nix.

Nix Setup

1. If you haven't already, install Nix
   • On POSIX systems, this is usually curl -L https://nixos.org/nix/install | sh
2. Run nix flake show --allow-import-from-derivation to verify that the flake can be read correctly by nix.
3. Build libraries: nix build
4. Start a devshell: nix develop -c {your shell}

If you have trouble, refer to the Nix Reference Manual for additional detail.

Haskell Setup

Since this project uses nix, you don't need to install either Stack or Yesod on your system, you can run it from a shell. In fact, the project already comes with a pre-configured shell. However, we'll show you how to obtain them using a shell or by configuring Nix/NixOS.

1. Make sure you have the yesod command line tool declared

   • Via nix-shell:

     nix-shell -p haskellPackages.yesod-bin stack

   • Via NixOS Configuration:

     environment.systemPackages = [
       pkgs.haskellPackages.yesod-bin
       pkgs.stack
     ];

2. Init a shell: nix develop -c {your shell}

3. Build libraries: stack build

If you have trouble, refer to the Yesod Quickstart guide for additional detail.

Development

Be sure that approot:" line on config/settings.yml is commented (approot will default to localhost, which we want for a local deployment).

Start a development server with:

  nix develop -c {your shell}
  stack exec -- yesod devel

As your code changes, your site will be automatically recompiled and redeployed to localhost. stack exec is only needed on the first run.

Tests

  nix develop -c {your shell}
  stack test --flag nixTalk:library-only --flag nixTalk:dev

(Because yesod devel passes the library-only and dev flags, matching those flags means you don't need to recompile between tests and development, and it disables optimization to speed up your test compile times).

Preparing to deploy

Prerequisites

1. Have a Cloud Console account with the credentials specified for the project (project, serviceAccount, accessKey) or change accordingly.
2. Have a record pointing to <this-yesod-app-name-dns> (```@````), or change the nginx options on /nixosModules/Nginx.nix accordingly.

Steps

1. Local Deploy Test

  cd /path/to/project/<this-yesod-app-name>
  git checkout <release-name>

Comment and change main configs on config/settings.yml to local configs.

  nix develop -c {your shell}
  stack exec yesod devel

If the deploy test doesn't work, go back to the main branch and make the necessary changes and repeat this step.

  exit

2. Local Build Test

  cd /path/to/project/<this-yesod-app-name>
  git checkout <release-name>

Comment and change local configs on config/settings.yml to main configs.

  nix develop -c {your shell}
  nix flake show --allow-import-from-derivation
  nix build
  exit

If the build test doesn't work, go back to the main branch and make the necessary changes and repeat from local deploy test.

Documentation

• Check nix.dev for the official documentation for the Nix ecosystem.
• Read the Yesod Book online for free
• Check Stackage for documentation on the packages in your LTS Haskell version, or search it using Hoogle. Tip: Your LTS version is in your stack.yaml file.
• For local documentation, use:
  • stack haddock --open to generate Haddock documentation for your dependencies, and open that documentation in a browser
  • stack hoogle <function, module or type signature> to generate a Hoogle database and search for your query
• The Yesod cookbook has sample code for various needs

Getting Help

• Ask questions and check other forums on NixOS Discourse
• Ask and contribute to the nix ecosystem on Nix/Nixpkgs/NixOS GitHub
• Ask questions on Stack Overflow, using the Yesod or Haskell tags
• Ask the Yesod Google Group
• There are several chatrooms you can ask for help:
  • For IRC, try Freenode#yesod and Freenode#haskell
  • Functional Programming Slack, in the #haskell, #haskell-beginners, or #yesod channels.

Credits and Licenses

This project includes code derived from YesodWeb/Yesod, which is licensed under the MIT License.
Additional modifications and original code in this repository are licensed under the BSD 3-Clause License.