git.iko.soy/obelisk
on master help sign in
readme, faq: Move some sections out of README into FAQ
commit576474f828f995a347d43b997cf26bd917cf344c authorElliot Cameron <eacameron@gmail.com> dateFri 5 Jun 2020, 12:01 (6 years ago) parent6eca276
2 files changed+58−59
compare with master
unifiedsplit
FAQ.md+58 README.md−59
FAQ.md+58
@@ -1,9 +1,67 @@
11# Frequently Asked Questions
22
3+1. [How do I declare a new Haskell dependency?](#how-do-i-declare-a-new-haskell-dependency)
4+1. [How do I add or override Haskell dependencies in the package set?](#how-do-i-add-or-override-haskell-dependencies-in-the-package-set)
5+1. [How do I extend my Obelisk application with more local packages?](#how-do-i-extend-my-obelisk-application-with-more-local-packages)
6+1. [How do I use `ob run` over HTTPS?](#how-do-i-use-ob-run-over-https)
371. [How do I fix invalid entitlements?](#how-do-i-fix-invalid-entitlements)
481. [`ob thunk update` or `ob deploy update` fails](#ob-thunk-update-or-ob-deploy-update-fails)
591. [How do I fix `Ambiguous module name` errors?](#how-do-i-fix-ambiguous-module-name-errors)
610
11+### How do I declare a new Haskell dependency?
12+
13+Every 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 it's 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. Refer to
14+
15+### How do I add or override Haskell dependencies in the package set?
16+
17+To 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:
18+
19+```nix
20+# ...
21+project ./. ({ 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+```
41+
42+For further information see [the Haskell section](https://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure) of nixpkgs "Contributors Guide".
43+
44+### How do I extend my Obelisk application with more local packages?
45+
46+If 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.
47+
48+```nix
49+# ...
50+project ./. ({ pkgs, ... }: {
51+# ...
52+ packages = {
53+ another = ./another;
54+ };
55+# ...
56+```
57+
58+### How do I use `ob run` over HTTPS?
59+
60+To run your app locally over HTTPS update the protocol in `config/common/route` to `https`, and then use `ob run` as normal.
61+
62+Obelisk 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.
63+
64+
765### How do I fix invalid entitlements?
866
967You probably did not set `ios.bundleIdentifier` correctly in `default.nix`.
README.md−59
@@ -12,9 +12,6 @@ Obelisk is an opinionated, batteries-included framework for building production-
1212 - [Who should consider using it?](#who-should-consider-using-it)
1313- [Installing Obelisk](#installing-obelisk)
1414- [Developing an Obelisk project](#developing-an-obelisk-project)
15− - [Adding Packages](#adding-packages)
16− - [Adding Package Overrides](#adding-package-overrides)
17− - [Running over HTTPS](#running-over-https)
1815 - [IDE Support](#ide-support)
1916 - [Terminal-based feedback](#terminal-based-feedback)
2017- [Deploying](#deploying)
@@ -98,62 +95,6 @@ Firefox will not be able to properly run the development website due to [issue 4
9895
9996Every time you change the Haskell source files in frontend, common or backend, `ob run` will automatically recompile the modified files and reload the server. Furthermore, it will display on screen compilation errors and warnings if any.
10097
101−### Adding packages
102−
103−In order to add package dependencies, declare them under the build-depends field in the appropriate cabal files (backend, common, and frontend each have their own). The corresponding Nix packages will automatically be selected when building.
104−
105−### Adding package overrides
106−
107−To add a version override to any Haskell package, or to add a Haskell package that doesn't exist in the nixpkgs used by Obelisk, 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:
108−
109−```nix
110−# ...
111−project ./. ({ pkgs, ... }: {
112−# ...
113− overrides = self: super: let
114− aesonSrc = pkgs.fetchFromGitHub {
115− owner = "obsidiansystems";
116− repo = "aeson-gadt-th";
117− rev = "ed573c2cccf54d72aa6279026752a3fecf9c1383";
118− sha256 = "08q6rnz7w9pn76jkrafig6f50yd0f77z48rk2z5iyyl2jbhcbhx3";
119− };
120− in
121− {
122− aeson = self.callCabal2nix "aeson" aesonSrc {};
123− waargonaut = self.callHackageDirect {
124− pkg = "waargonaut";
125− ver = "0.8.0.1";
126− sha256 = "1zv28np3k3hg378vqm89v802xr0g8cwk7gy3mr77xrzy5jbgpa39";
127− } {};
128− };
129−# ...
130−```
131−
132−For further information see [the Haskell section](https://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure) of nixpkgs Contributors Guide.
133−
134−### Adding extra local packages
135−
136−If the standard packages (`frontend`, `backend`, and `common`) are not
137−enough, to add more local Haskell packages, define them with the
138−`packages` parameter. The sources of these packages will be
139−automatically reloaded by `ob run`.
140−
141−```nix
142−# ...
143−project ./. ({ pkgs, ... }: {
144−# ...
145− packages = {
146− another = ./another;
147− };
148−# ...
149−```
150−
151−### Running over HTTPS
152−
153−To run your app locally over HTTPS, update the protocol in `config/common/route` to `https`, and then use `ob run` as normal.
154−
155−Since Obelisk generates a self-signed certificate for running HTTPS, 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.
156−
15798### IDE Support
15899
159100#### Terminal-based feedback