Skip to content

Commit c3a7481

Browse files
committed
update HACKING.md for dune pkg, CONTRIBUTING.md doesn't need updating
1 parent 1c29615 commit c3a7481

File tree

1 file changed

+13
-51
lines changed

1 file changed

+13
-51
lines changed

HACKING.md

Lines changed: 13 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -24,32 +24,18 @@ git clone https://github.com/<username>/OCaml.org.git
2424
cd OCaml.org
2525
```
2626

27-
Ensure you have `opam` installed. Opam will manage the OCaml compiler along with all of the OCaml packages needed to build and run the project. By this point, we should all be using some Unix-like system (Linux, macOS, WSL2), so you should [run the opam install script](https://opam.OCaml.org/doc/Install.html#Binary-distribution). There are also manual instructions for people that don't want to run a script from the internet. We assume you are using `opam.2.1.0` or later, which provides a cleaner, friendlier experience when installing system dependencies.
28-
29-
With opam installed, you can now initialise opam with `opam init`. Note that in containers or WSL2, you will have to run `opam init --disable-sandboxing`. Opam might complain about some missing system dependencies like `unzip`, `cc` (a C compiler like `gcc`), etc. Make sure to install these before `opam init`.
30-
31-
Finally from the root of your project, you can setup a [local opam switch](https://opam.OCaml.org/doc/Manual.html#Switches) and install the dependencies. There is a single `make` target to do just that.
32-
33-
```
34-
make switch
35-
```
36-
37-
If you don't want a local opam switch and are happy to install everything globally (in the opam sense), then you can just install the dependencies directly.
38-
39-
```
40-
make deps
41-
```
42-
43-
Opam will likely ask questions about installing system dependencies. Ror the project to work, you will have to answer yes to installing these.
27+
Ensure you have [Dune Developer Preview](https://preview.dune.build) installed. Dune will manage the OCaml compiler along with all of the OCaml packages needed to build and run the project. By this point, we should all be using some Unix-like system (Linux, macOS, WSL2). We assume you are using the most recent version of Dune Developer Preview.
4428

4529
### Running the Server
4630

47-
After building the project, you can run the server with:
31+
From the root of your project, you can just build and run the project with
4832

49-
```bash
33+
```
5034
make start
5135
```
5236

37+
Dune will install the OCaml compiler, as well as all the dependencies needed by the project.
38+
5339
To start the server in watch mode, you can run:
5440

5541
```bash
@@ -80,13 +66,7 @@ The OCaml Playground is compiled separately from the rest of the server. The gen
8066

8167
You can build the playground from the root of the project. There is no need to move to the `./playground/` directory for the following commands.
8268

83-
To regenerate the playground, you need to install the playground's dependencies first:
84-
85-
```
86-
make deps -C playground
87-
```
88-
89-
After the dependencies have been installed, simply build the project to regenerate the JavaScript assets:
69+
Simply build the project to regenerate the JavaScript assets:
9070

9171
```
9272
make playground
@@ -127,30 +107,13 @@ before they get merged.
127107

128108
### Managing Dependencies
129109

130-
OCaml.org is using an opam switch that is local and bound to a pinned commit in `opam-repository`. This is intended to protect the build from upstream regressions. The opam repository is specified in three (3) places:
110+
OCaml.org is using an pinned version of `opam-repository`. This is intended to protect the build from upstream regressions. The opam repository is specified in one place:
131111

132112
```
133-
Dockerfile
134-
Makefile
135-
.github/workflows/*.yml
136-
```
137-
138-
When bringing up OCaml.org to a newer pin, the commit hash found it those files must be changed all at once.
139-
140-
Once the opam repo pin is updated, the local switch must be updated using the following command:
141-
142-
```sh
143-
opam repo set-url pin git+https://github.com/ocaml/opam-repository#<commit-hash>
113+
dune-workspace
144114
```
145115

146-
Where `<commit-hash>` is the pinned hash specified in the files mentioned above.
147-
148-
Once this is done, you can run `opam update` and `opam upgrade`. If OCamlFormat
149-
was upgraded in the process, the files `.ocamlformat` and
150-
`.github/workflows/ci.yml` must be modified with the currently installed version
151-
of OCamlFormat.
152-
153-
### Handling the Tailwind CSS
116+
### Handling the Tailwind CSS CLI
154117

155118
The Tailwind CSS framework. The tailwind binary pulled from its GitHub [repo](https://github.com/tailwindlabs/tailwindcss). Download is performed by Dune during the build. When working on a local switch for hacking, you don't want `dune clean` to delete this binary. Just do `dune install tailwind` to have it installed in the local switch.
156119

@@ -191,11 +154,10 @@ The following snippet describes the repository structure:
191154
├── dune
192155
├── dune-project
193156
│ Dune file used to mark the root of the project and define project-wide parameters.
194-
│ For the documentation of the syntax, see https://dune.readthedocs.io/en/stable/dune-files.html#dune-project.
195-
196-
├── ocamlorg.opam
197-
├── ocamlorg.opam.template
198-
│ opam package definitions.
157+
│ For the documentation of the syntax, see https://dune.readthedocs.io/en/latest/reference/dune-project/index.html.
158+
├── dune-workspace
159+
│ Dune file used to define the repositories used for dependencies by Dune package management
160+
│ For the documentation of the syntax, see https://dune.readthedocs.io/en/latest/reference/dune-workspace/index.html.
199161
200162
├── CONTRIBUTING.md
201163

0 commit comments

Comments
 (0)