git.iko.soy/obelisk
on jb-ignore-package-environment help sign in
obelisk/FAQ.md
122 lines 6.3 kB history raw
1# Frequently Asked Questions
31. [How do I fix invalid entitlements? ](#how-do-i-fix-invalid-entitlements)
41. [`ob thunk update` or `ob deploy update` fails](#ob-thunk-update-or-ob-deploy-update-fails)
51. [How do I fix `Ambiguous module name` errors?](#how-do-i-fix-ambiguous-module-name-errors)
61. [What does `ob run` actually do?](#what-does-ob-run-actually-do)
8### How do I fix invalid entitlements?
10You probably did not set `ios.bundleIdentifier` correctly in `default.nix`.
11When this happens you'll see an error something like this:
13```
142018-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)
15```
17Fixing the value of `ios.bundleIdentifier` should fix the error.
19### `ob thunk update` or `ob deploy update` fails
20Whenever an `ob` command fails, try re-running it with `-v`.
22If 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:
24```
25Starting Obelisk </nix/store/j8wls8a89xr6s1a47lg6g83gnbdrfd0l-obelisk-command-0.1/bin/.ob-wrapped> args=["deploy","update","-v"] logging-level=Debug
26Creating process: 'nix-build' './.obelisk/impl' '-A' 'command' '--no-out-link'
27✔ Built on ./.obelisk/impl [command]
28Handing off to /nix/store/j8wls8a89xr6s1a47lg6g83gnbdrfd0l-obelisk-command-0.1/bin/ob
29Starting Obelisk </nix/store/j8wls8a89xr6s1a47lg6g83gnbdrfd0l-obelisk-command-0.1/bin/.ob-wrapped> args=["--no-handoff","deploy","update","-v"] logging-level=Debug
30Creating process: 'git' 'ls-remote' '--exit-code' '--symref' 'https://github.com/obsidiansystems/some-private-repo.git' 'refs/heads/master'
31git ls-remote maps: (fromList [],fromList [(GitRef_Branch "master","8546dfc8be9653f20bb26214e0991dbb957cb290")])
32Latest commit in branch master from remote repo https://github.com/obsidiansystems/some-private-repo.git is 8546dfc8be9653f20bb26214e0991dbb957cb290
33Creating process: 'nix-prefetch-url' '--unpack' '--type' 'sha256' 'https://github.com/obsidiansystems/some-private-repo/archive/8546dfc8be9653f20bb26214e0991dbb957cb290.tar.gz'
34error: unable to download 'https://github.com/obsidiansystems/some-private-repo/archive/8546dfc8be9653f20bb26214e0991dbb957cb290.tar.gz': HTTP error 404
35Process exited with code 1; 'nix-prefetch-url' '--unpack' '--type' 'sha256' 'https://github.com/obsidiansystems/some-private-repo/archive/8546dfc8be9653f20bb26214e0991dbb957cb290.tar.gz'
36nix-prefetch-url: Failed to determine sha256 hash of URL https://github.com/obsidiansystems/some-private-repo/archive/8546dfc8be9653f20bb26214e0991dbb957cb290.tar.gz
37✖ Updating thunk ./src to latest
38```
40And here's how you can fix it:
42```
43ob thunk unpack $SOME_THUNK
44ob thunk pack $SOME_THUNK
45```
46Substitute the directory of your thunk for `$SOME_THUNK`. In the case of `ob deploy update`, `$SOME_THUNK` will be `src` in the deployment directory.
48(Based on issue #351).
50### How do I fix `Ambiguous module name` errors?
51Since 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.
53You 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
54```
55error:
56 Ambiguous module name ‘Crypto.Hash’:
57 it was found in multiple packages:
58 cryptohash-0.11.9 cryptonite-0.25
59```
60then specify the package you want in the import, e.g:
61`import "cryptonite" Crypto.Hash`
64### What does `ob run` actually do?
67#### Short version:
69`ob run` starts a [`ghcid`](https://github.com/ndmitchell/ghcid) process which
70tries to build your project within a carefully crafted `nix-shell` with all the
71project's dependencies and,
73* either displays compilation errors/warnings,
74* or starts the Obelisk server, which serves:
75 * your backend's route handlers,
76 * the static assets,
77 * the [JSaddle](https://github.com/ghcjs/jsaddle) frontend code (while opening its websocket).
79#### Longer version:
81Assuming we are in a project created with `ob init`, `ob run` calls (see
82`lib/command/src/Obelisk/Command.hs`):
84 nix-shell --pure --keep NIX_PATH -A shells.ghc --run 'ob --no-handoff internal run-static-io <real-run-function>'
86where
88* `shells.ghc` is defined in `./default.nix` by importing `./.obelisk/impl/default.nix` which
89 is `default.nix` in the present (Obelisk) repository,
90* `run-static-io` is a logging-enabled command wrapper
91 (cf. `runObelisk` in `lib/command/src/Obelisk/App.hs`).
93In this case, it runs the function `Obelisk.Command.Command.run` (defined in
94`lib/command/src/Obelisk/Command/Run.hs`).
96* It creates a GHCi config from a Nix expression which:
97 * loads three packages: `backend`, `common`, `frontend`,
98 * obtains a free port number.
99* Then runs `ghcid`
100 * with a command that reruns `Obelisk.Run.run` at each restart (option
101 `--test`).
103It is defined in `lib/run/src/Obelisk/Run.hs`:
105* It creates a thread which starts the main backend.
106 This runs `runSnapWithCommandLineArgs` and passes routes:
107 * to the backend (result of the `_backend_run` field of your
108 implementation of the `Backend fullRoute frontendRoute` record),
109 * or to `serveDefaultObeliskApp` (`lib/backend/src/Obelisk/Backend.hs`) to
110 serve static assets.
111* Starts `runWidget`
112 which itself runs
113 [runSettingsSocket](https://hackage.haskell.org/package/warp-3.2.26/docs/Network-Wai-Handler-Warp.html#v:runSettingsSocket)
114 (the *“TCP listen loop”*):
115 * it binds to TCP socket, and
116 * creates the HTTP connection manager
117 ( [`newManager`](https://hackage.haskell.org/package/http-client-0.6.3/docs/Network-HTTP-Client.html#v:newManager))
118 * calls `obeliskApp` which
119 * has a route to serve the [JSaddle](https://github.com/ghcjs/jsaddle) frontend,
120 * runs the frontend (*on* the server), to produce pre-rendered pages,
121 * starts the JSaddle web-socket,
122 * “falls back” to proxying the backend (`fallbackProxy`).