Skip to content

Commit 50a13c7

Browse files
rebeccaskinnerrebeccaskinner
authored
Merge pull request #94 from haskell-infra/nix-cleanup
refactor buildAndWatch to run outside of the nix shell
2 parents 91de132 + 463d228 commit 50a13c7

File tree

3 files changed

+173
-16
lines changed

3 files changed

+173
-16
lines changed

Diff for: ‎README.md

+57-14
Original file line numberDiff line numberDiff line change
@@ -11,25 +11,68 @@ Some of the others are
1111
* www.haskell.org/platform (built from [haskell-platform](https://github.com/haskell/haskell-platform/tree/master/website))
1212
* www.haskell.org/ghcup (build from [ghcup-hs](https://gitlab.haskell.org/haskell/ghcup-hs/-/tree/master/www)
1313

14-
### Cabal instructions
15-
Just run `cabal v2-build` to build or `cabal v2-run` to run, and `cabal v2-run -- build` to actually build the site.
14+
### Contributing Changes
1615

17-
### Nix instructions
16+
The easiest way to make changes is to use the `buildAndWatch` script and then
17+
point your web browser to [http://localhost:8000](http://localhost:8000). When
18+
you are finished editing or want to re-build the hakyll part of the site, you
19+
can stop the script by pressing `Control+c` (`C-c`).
1820

19-
This repo provides haskell.org as a nix derivation of a hakyll built static site. The `default.nix` file returns a set with two elements
20-
- builder (the hakyll binary which processes source into the static site)
21-
- built (the static site built by the builder, and ready to serve)
21+
If you are only making changes to the content of the site, you can leave this
22+
script running and it will automatically pick up changes and re-build the site
23+
for you.
2224

23-
### Developing
25+
If you want to change the `builder`, or if you encounter an error where your
26+
changes to the content aren't being picked up, need to stop the script and
27+
re-start it.
2428

25-
Simply run `nix-shell`. This will allow you to build the `haskell-org-site` binary which in turn builds the static site.
26-
You may also edit the content of the site in the shell.
29+
Once you're satisfied with your changes, make a PR and the maintainers will try
30+
to review it as soon as we can.
2731

28-
### Editing
32+
### Working On The Builder
2933

30-
You may install the `haskell-org-site` binary locally with `nix-env -f . -iA builder`. Once `haskell-org-site` is on your path you can edit content, and have
31-
the site served with `site watch`.
34+
The `builder` is the static site generator that turns the markdown files, CSS,
35+
images, and scripts into a website. It lives in the `builder`. Most of the time,
36+
you won't need to make changes to the builder and you can follow the
37+
instructions in the _Contributing Changes_ section above.
3238

33-
### Building
39+
If you want to make a quick change or two, you can continue to use the
40+
`buildAndWatch` script to rebuild changes, but for more substantial changes this
41+
might increase the build cycle time too much. In this case, you can build the
42+
builder using either nix or cabal. Directions for both are given below:
3443

35-
To obtain the static `haskell-org-site` simply run `nix-build -A built` and the generated `result` link will contain the static site contents.
44+
<a id="buildingWithoutNix"></a>
45+
### Manually Building the Site With Cabal
46+
47+
If you don't have nix installed, or if you are inside of the project's nix
48+
shell, you will want to use cabal to compile the builder. To do so, enter the
49+
`builder` directory and compile the program with:
50+
51+
```shell
52+
cabal v2-build
53+
```
54+
55+
Once compiled, the builder must be run from the project root directory so that
56+
it can find all of the content. To run the builder, you need to first find the
57+
name of the executable. From the builder directory, you can find the executable
58+
path by running:
59+
60+
```
61+
find dist-newstyle -name 'haskell-org-site' -type f
62+
```
63+
64+
Using that path, you can run the builder from the project root directory.
65+
66+
### Manually Building the Site With Nix
67+
68+
If you have nix installed, you can have nix build the builder by running:
69+
70+
```
71+
nix-build -A builder
72+
```
73+
74+
You may then run the builder binary from the `result` directory:
75+
76+
```
77+
./result/bin/haskell-org-site build
78+
```

Diff for: ‎buildAndWatch

+116
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
#!/usr/bin/env bash
2+
set -eou pipefail
3+
4+
function buildAndWatchWithNix() {
5+
if [[ -n "${IN_NIX_SHELL+x}" ]]; then
6+
echo "buildAndWatch does not work inside of a nix shell. Please exit the nix-shell and retry."
7+
exit 1
8+
fi
9+
10+
if [[ ! -x $(type -P "nix-build") ]]; then
11+
echo "nix-build is not available. Please install nix from https://nixos.org/download.html"
12+
exit 1
13+
fi
14+
15+
nix-build -A builder && \
16+
./result/bin/haskell-org-site clean && \
17+
./result/bin/haskell-org-site build && \
18+
./result/bin/haskell-org-site watch
19+
exit 0
20+
}
21+
22+
function buildAndWatchWithoutNix() {
23+
if [[ ! -x $(type -P "cabal") ]]; then
24+
echo "Please download and install a haskell environment. See: https://www.haskell.org/downloads/"
25+
exit 1
26+
fi
27+
28+
pushd builder
29+
cabal v2-build
30+
builderPath=$(find dist-newstyle -name 'haskell-org-site' -type f)
31+
popd
32+
builder="./builder/${builderPath}"
33+
34+
if [[ ! -x "${builder}" ]]; then
35+
cat <<EOF
36+
After building 'haskell-org-site' I was unable to find the path to a
37+
runnable executable. This may be because of a bug in this script. You
38+
may want to try to build and run the builder manually, ask for help,
39+
or submit a bug report.
40+
EOF
41+
exit 1
42+
fi
43+
44+
"${builder}" clean
45+
"${builder}" build
46+
"${builder}" watch
47+
exit 0
48+
}
49+
50+
function buildAndWatchAuto() {
51+
if [[ -x $(type -P "nix-build") ]]; then
52+
if [[ -n "${IN_NIX_SHELL+x}" ]]; then
53+
cat <<EOF
54+
I found a 'nix' installation, but we're currently inside of a nix
55+
shell. I will try to build using cabal. If building with cabal fails,
56+
you should try to re-run this script when you are not inside of a nix
57+
shell.
58+
EOF
59+
buildAndWatchWithoutNix
60+
else
61+
buildAndWatchWithNix
62+
fi
63+
else
64+
buildAndWatchWithoutNix
65+
fi
66+
}
67+
68+
function showHelp() {
69+
cat <<EOF
70+
Usage: buildAndWatch [buildMode]
71+
72+
Build the haskell.org site builder, compile the site, and start a
73+
local server on port 8000 to preview changes.
74+
75+
buildAndWatch takes a single optional argument, 'buildMode'. If it's
76+
omitted, buildAndWatch will attempt to select the best method for
77+
building the site based on your current environment. If you provide an
78+
argument, it may be one of the following:
79+
80+
auto (default) Automatically select between 'nix' or 'cabal' based on the
81+
current environment.
82+
nix Use nix to build the site
83+
cabal Use cabal to build the site. If you are in a nix shell,
84+
it will use your nix environment. Otherwise, it will use
85+
your system-wide cabal installation.
86+
help Show this help message and exit
87+
EOF
88+
}
89+
90+
91+
function buildAndWatchWithArgs() {
92+
case ${1} in
93+
"auto")
94+
buildAndWatchAuto
95+
;;
96+
"nix")
97+
buildAndWatchWithNix
98+
;;
99+
"cabal")
100+
buildAndWatchWithoutNix
101+
;;
102+
"help")
103+
showHelp
104+
;;
105+
*)
106+
echo "Unrecognized or missing arguments"
107+
showHelp
108+
exit 1
109+
esac
110+
}
111+
112+
if [[ $# -gt 0 ]]; then
113+
buildAndWatchWithArgs "${1}"
114+
else
115+
buildAndWatchWithArgs "auto"
116+
fi

Diff for: ‎builder/default.nix

-2
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,8 @@
2727
LOCALE_ARCHIVE = "${pkgs.glibcLocales}/lib/locale/locale-archive";
2828
LC_ALL = "C.UTF-8";
2929
shellHook = ''
30-
alias buildAndWatch="cabal configure && cabal build && cabal exec haskell-org-site -- clean && cabal exec haskell-org-site -- watch"
3130
echo ""
3231
echo " Haskell.org Dev Shell"
33-
echo " \`buildAndWatch\` to serve the site, and rebuild when files change."
3432
echo " \`linkchecker\`, \`ghcid\` and \`cabal\` are provided in this environment."
3533
echo ""
3634
'';

0 commit comments

Comments
 (0)