git.iko.soy/obelisk
on master help sign in
obelisk/FAQ.md
117 lines 6.8 kB history raw
1# Frequently Asked Questions
31. [How do I declare a new Haskell dependency?](#how-do-i-declare-a-new-haskell-dependency)
41. [How do I add or override Haskell dependencies in the package set?](#how-do-i-add-or-override-haskell-dependencies-in-the-package-set)
51. [How do I extend my Obelisk application with more local packages?](#how-do-i-extend-my-obelisk-application-with-more-local-packages)
61. [How do I use `ob run` over HTTPS?](#how-do-i-use-ob-run-over-https)
71. [How do I fix invalid entitlements?](#how-do-i-fix-invalid-entitlements)
81. [`ob thunk update` or `ob deploy update` fails](#ob-thunk-update-or-ob-deploy-update-fails)
91. [How do I fix `Ambiguous module name` errors?](#how-do-i-fix-ambiguous-module-name-errors)
11### How do I declare a new Haskell dependency?
13Every component of your Obelisk application is a standard [cabal](https://www.haskell.org/cabal/) package. That means declaring new Haskell dependencies simply involves updating the `build-depends` field in the appropriate cabal file (`backend.cabal` for example). By default, Obelisk will use its curated package set to choose which version of each package you get. It's possible that the package you need is not already in the curated set or the curated version isn't the one you want. See [How do I add or override Haskell dependencies in the package set?](#how-do-i-add-or-override-haskell-dependencies-in-the-package-set) for a solution to this.
15### How do I add or override Haskell dependencies in the package set?
17To add a Haskell package that doesn't exist in Obelisk's package set or to override the version of a package, use the `overrides` attribute in your project's `default.nix`. For example, to use a specific version of the `aeson` package fetched from GitHub and a specific version of the `waargonaut` package fetched from Hackage, your `default.nix` will look like:
19```nix
20# ...
21project ./. ({ pkgs, ... }: {
22# ...
23 overrides = self: super: let
24 aesonSrc = pkgs.fetchFromGitHub {
25 owner = "obsidiansystems";
26 repo = "aeson-gadt-th";
27 rev = "ed573c2cccf54d72aa6279026752a3fecf9c1383";
28 sha256 = "08q6rnz7w9pn76jkrafig6f50yd0f77z48rk2z5iyyl2jbhcbhx3";
29 };
30 in
31 {
32 aeson = self.callCabal2nix "aeson" aesonSrc {};
33 waargonaut = self.callHackageDirect {
34 pkg = "waargonaut";
35 ver = "0.8.0.1";
36 sha256 = "1zv28np3k3hg378vqm89v802xr0g8cwk7gy3mr77xrzy5jbgpa39";
37 } {};
38 };
39# ...
40```
42For further information see [the Haskell section](https://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure) of nixpkgs "Contributors Guide".
44### How do I extend my Obelisk application with more local packages?
46If the standard packages (`frontend`, `backend`, and `common`) are not enough, you may add more local packages by defining them with the `packages` attribute in your `default.nix`. The sources of these packages will be automatically loaded by `ob run`/`ob repl`/etc.
48```nix
49# ...
50project ./. ({ pkgs, ... }: {
51# ...
52 packages = {
53 another = ./dep/another;
54 };
55# ...
56```
58### How do I use `ob run` over HTTPS?
60To run your app locally over HTTPS, update the protocol in `config/common/route` to `https`, and then use `ob run` as normal.
62Obelisk generates a self-signed certificate for running HTTPS so the browser will issue a warning about using an invalid certificate. On Chrome, you can go to `chrome://flags/#allow-insecure-localhost` to enable invalid certificates for localhost.
65### How do I fix invalid entitlements?
67You probably did not set `ios.bundleIdentifier` correctly in `default.nix`. When this happens you'll see an error something like this:
69```
702018-11-25 09:34:22.438 ios-deploy[58106:8521046] [ !! ] Error 0xe8008016: The executable was signed with invalid entitlements. AMDeviceSecureInstallApplication(0, device, url, options, install_callback, 0)
71```
73Fixing the value of `ios.bundleIdentifier` should fix the error.
75### `ob thunk update` or `ob deploy update` fails
76Whenever an `ob` command fails, try re-running it with `-v`.
78If you're using a private repo, and you get a failure in `nix-prefetch-url`, you may need to unpack and repack the thunk. Here's some example output that shows this issue:
80```
81Starting Obelisk </nix/store/j8wls8a89xr6s1a47lg6g83gnbdrfd0l-obelisk-command-0.1/bin/.ob-wrapped> args=["deploy","update","-v"] logging-level=Debug
82Creating process: 'nix-build' './.obelisk/impl' '-A' 'command' '--no-out-link'
83✔ Built on ./.obelisk/impl [command]
84Handing off to /nix/store/j8wls8a89xr6s1a47lg6g83gnbdrfd0l-obelisk-command-0.1/bin/ob
85Starting Obelisk </nix/store/j8wls8a89xr6s1a47lg6g83gnbdrfd0l-obelisk-command-0.1/bin/.ob-wrapped> args=["--no-handoff","deploy","update","-v"] logging-level=Debug
86Creating process: 'git' 'ls-remote' '--exit-code' '--symref' 'https://github.com/obsidiansystems/some-private-repo.git' 'refs/heads/master'
87git ls-remote maps: (fromList [],fromList [(GitRef_Branch "master","8546dfc8be9653f20bb26214e0991dbb957cb290")])
88Latest commit in branch master from remote repo https://github.com/obsidiansystems/some-private-repo.git is 8546dfc8be9653f20bb26214e0991dbb957cb290
89Creating process: 'nix-prefetch-url' '--unpack' '--type' 'sha256' 'https://github.com/obsidiansystems/some-private-repo/archive/8546dfc8be9653f20bb26214e0991dbb957cb290.tar.gz'
90error: unable to download 'https://github.com/obsidiansystems/some-private-repo/archive/8546dfc8be9653f20bb26214e0991dbb957cb290.tar.gz': HTTP error 404
91Process exited with code 1; 'nix-prefetch-url' '--unpack' '--type' 'sha256' 'https://github.com/obsidiansystems/some-private-repo/archive/8546dfc8be9653f20bb26214e0991dbb957cb290.tar.gz'
92nix-prefetch-url: Failed to determine sha256 hash of URL https://github.com/obsidiansystems/some-private-repo/archive/8546dfc8be9653f20bb26214e0991dbb957cb290.tar.gz
93✖ Updating thunk ./src to latest
94```
96And here's how you can fix it:
98```bash
99ob thunk unpack $SOME_THUNK
100ob thunk pack $SOME_THUNK
101```
102Substitute the directory of your thunk for `$SOME_THUNK`. In the case of `ob deploy update`, `$SOME_THUNK` will be `src` in the deployment directory.
104(Based on issue #351).
106### How do I fix `Ambiguous module name` errors?
107Since obelisk places the common/backend/frontend modules packages into the same ghci, and ghci doesn't "sandbox" them, it is possible to have conflicting module errors inside `ob repl/watch/run` that do not appear when doing a cabal build.
109You can disambiguate this via [PackageImports](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/glasgow_exts.html#package-qualified-imports). For instance, if you see
110```
111error:
112 Ambiguous module name ‘Crypto.Hash’:
113 it was found in multiple packages:
114 cryptohash-0.11.9 cryptonite-0.25
115```
116then specify the package you want in the import, e.g:
117`import "cryptonite" Crypto.Hash`