V2 of Real World OCaml https://dev.realworldocaml.org

Yaron Minsky 3bb9654c0f Merge pull request #3267 from shakthimaan/guided-tour/use-z-instead-of-x-in-nesting-lets-with-let-and-in 3 weeks ago
bin 942bf4c649 Work around dune 2's read only targets in PDF generation 3 weeks ago
book 3bb9654c0f Merge pull request #3267 from shakthimaan/guided-tour/use-z-instead-of-x-in-nesting-lets-with-let-and-in 3 weeks ago
duniverse 33139c3533 Update dune and dune-configurator to 2.4.0 3 weeks ago
scripts 62cb5053b8 update to opam2 files and Dockerfiles 1 year ago
static 942bf4c649 Work around dune 2's read only targets in PDF generation 3 weeks ago
.dockerignore 539f4051ae port to a monorepo 2 years ago
.gitattributes a992ae296a Add a .gitattributes file 2 years ago
.gitignore 62cb5053b8 update to opam2 files and Dockerfiles 1 year ago
.hgignore ff8a30398e added hgignore, so I can use hg-git properly 2 years ago
.travis.yml c1e2b58573 Use upstream travis-ci tool to fix deployment issue 1 year ago
Dockerfile 33139c3533 Update dune and dune-configurator to 2.4.0 3 weeks ago
LICENSE.md 0f3e970817 add LICENSE for the various uses in this repo 6 months ago
Makefile 462ea0033d Update Makefile and dune-get for latest duniverse 1 month ago
NOTES.md 9a60873794 Rename .topscript files into .mlt 2 years ago
README.md 1e6dd9cdaa Bump dune version in README.md 2 months ago
dune-get 33139c3533 Update dune and dune-configurator to 2.4.0 3 weeks ago
dune-project 27c5b3b03f Use mdx stanza 3 weeks ago
rwo.opam 33139c3533 Update dune and dune-configurator to 2.4.0 3 weeks ago

README.md

Real World OCaml v2

This is the source code for the Real World OCaml 2nd edition, which is still a work in progress. The original edition was written by Yaron Minsky, Anil Madhavapeddy and Jason Hickey, and the revised edition is being lead by Yaron Minsky and Anil Madhavapeddy. There have been significant contributions to the revised tooling from Ashish Agarwal, Jeremy Yallop, Frederic Bour, and Sander Spies.

An online snapshot of the development book is available from https://dev.realworldocaml.org. There is a Feedback pane on each chapter which leads to a dedicated section on the OCaml discussion forum where you can register broader feedback. More specific issues such as typos can be reported on the issue tracker.

Repository layout

Each chapter of the book sits in a separate subfolder of the book/ directory. The README.md file contains the text of the chapter, written in markdown. Each ocaml or shell code block in the chapter is validated using mdx. The more complex and structured examples live in an examples/ sub folder and mdx is used to keep the examples and the chapter's code block in sync.

The bin/ folder contains the OCaml scripts used to generate the books HTML and PDF versions.

All of the code and examples are built using OCaml 4.09.0.

Building

Here are the commands to build the website:

Installing Dependencies

You can install system dependencies by running:

make depext

All OCaml dependencies are vendored in the duniverse/ directory except for the dune build system itself. It's preferable to use an empty opam switch with only dune installed to avoid conflicts between the opam and local libraries. To set up your RWO development environment you can run:

opam switch create rwo 4.09.0
opam install dune=2.0.1

Generating the HTML

To generate the HTML pages:

make

The HTML pages are created in _build/default/static/. Open _build/default/static/index.html to start browsing the freshly built version of the book.

Testing the code examples

It is possible to automatically test that the the code examples files work fine. To check that shell scripts and .ml files do what they are expected:

make test

This will run all the tests in "determinitic mode", which is suitable for the CI and it will display the diff between what is expected and what is produced.

To accept the changes:

make promote

Testing non-deterministic examples

A few code examples are not deterministic: for instance benchmarks. In this case, there is a special command to run:

make test-all

To accept the changes:

make promote

Upgrading or adding dependencies

RWO's dependencies are vendored using duniverse. If you want to upgrade them to their latest availbale opam version you can run:

make duniverse-upgrade

Additionally, if you're working on the book and need a new package vendored, you can simply add it to the $DEPS variable in the Makefile and run the above command again.

It's possible that after upgrading you get some errors because vendored dependencies use jbuild files instead of dune files and compatibility with those has been dropped in dune 2. You can upgrade those using the following command:

dune upgrade --root duniverse/<package_name>.<version>