Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use MDX to test the README example #991

Merged
merged 1 commit into from
Jan 6, 2022
Merged

Use MDX to test the README example #991

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 21 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,13 +51,15 @@ version and install instructions on [ocaml.org](https://ocaml.org/docs/install.h
To install Irmin with the command-line tool and all optional dependencies using
`opam`:

<!-- $MDX skip -->
```bash
opam install irmin-unix
```

A minimal installation containing the reference in-memory backend can be
installed by running:

<!-- $MDX skip -->
```bash
opam install irmin
```
Expand All @@ -79,6 +81,7 @@ The following packages have been made available on `opam`:

To install a specific package, simply run:

<!-- $MDX skip -->
```bash
opam install <package-name>
```
Expand All @@ -88,6 +91,7 @@ To install a specific package, simply run:
To install the development version of Irmin in your current `opam switch`, clone
this repository and `opam install` the packages inside:

<!-- $MDX skip -->
```bash
git clone https://github.com/mirage/irmin
cd irmin/
Expand All @@ -101,12 +105,12 @@ this repository and `opam install` the packages inside:
Below is a simple example of setting a key and getting the value out of a
Git-based, filesystem-backed store.

<!-- N.B. Any changes to the following example must be mirrored in `examples/readme.ml`. -->
<!-- $MDX file=examples/readme.ml -->
```ocaml
open Lwt.Syntax

(* Irmin store with string contents *)
module Store = Irmin_unix.Git.FS.KV(Irmin.Contents.String)
module Store = Irmin_unix.Git.FS.KV (Irmin.Contents.String)

(* Database configuration *)
let config = Irmin_git.config ~bare:true "/tmp/irmin/test"
Expand All @@ -126,12 +130,12 @@ let main =

(* Set key "foo/bar" to "testing 123" *)
let* () =
Store.set_exn t ~info:(info "Updating foo/bar") ["foo"; "bar"]
Store.set_exn t ~info:(info "Updating foo/bar") [ "foo"; "bar" ]
"testing 123"
in

(* Get key "foo/bar" and print it to stdout *)
let+ x = Store.get t ["foo"; "bar"] in
let+ x = Store.get t [ "foo"; "bar" ] in
Printf.printf "foo/bar => '%s'\n" x

(* Run the program *)
Expand All @@ -141,9 +145,12 @@ let () = Lwt_main.run main
The example is contained in [examples/readme.ml](./examples/readme.ml) It can
be compiled and executed with dune:

$ dune build examples/readme.exe
$ dune exec examples/readme.exe
foo/bar => 'testing 123'
<!-- $MDX skip -->
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this skipped?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think mdx has issues with running Dune from inside Dune:

 |```sh
 |$ dune build examples/readme.exe
-|$ dune exec examples/readme.exe
-|foo/bar => 'testing 123'
+|Error: Multiple rules generated for _build/default/examples/readme.exe:
+|- file present in source tree
+|- examples/dune:2
+|Hint: rm -f examples/readme.exe
+|[1]
+|$ dune exec examples/readme.exe
+|Error: Multiple rules generated for _build/default/examples/readme.exe:
+|- file present in source tree
+|- examples/dune:2
+|Hint: rm -f examples/readme.exe
+|[1]

but I may just be missing something 🙂

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that's weird, as it's something that is done in RWO without much trouble. Again please report it upstream so that it's tracked and solved properly :-)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks to me like RWO is cheating slightly by unsetting INSIDE_DUNE: https://github.com/realworldocaml/book/blame/master/book/testing/README.md#L544. I'll discuss this with @NathanReb when he gets back from holiday next week.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please open an issue so I can follow the discussion too ;-)

```bash
$ dune build examples/readme.exe
$ dune exec examples/readme.exe
foo/bar => 'testing 123'
```

The [examples](./examples/) directory also contains more advanced examples,
which can be executed in the same way.
Expand All @@ -153,10 +160,13 @@ which can be executed in the same way.
The same thing can also be accomplished using `irmin`, the command-line
application installed with `irmin-unix`, by running:

$ echo "root: ." > irmin.yml
$ irmin init
$ irmin set foo/bar "testing 123"
$ irmin get foo/bar
```bash
$ echo "root: ." > irmin.yml
$ irmin init
$ irmin set foo/bar "testing 123"
$ irmin get foo/bar
testing 123
```

`irmin.yml` allows for `irmin` flags to be set on a per-directory basis. You
can also set flags globally using `$HOME/.irmin/config.yml`. Run
Expand Down
4 changes: 4 additions & 0 deletions dune
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,5 @@
(vendored_dirs vendors)

(mdx
(files README.md)
(packages irmin irmin-unix))
1 change: 1 addition & 0 deletions dune-project
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@
(name irmin)
(allow_approximate_merlin)
(cram enable)
(using mdx 0.1)
19 changes: 0 additions & 19 deletions examples/readme.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,3 @@
(*
* Copyright (c) 2013-2021 Thomas Gazagnaire <thomas@gazagnaire.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*)

(* N.B. This excerpt is extracted from project README. Any changes made here
* should be mirrored there. *)

open Lwt.Syntax

(* Irmin store with string contents *)
Expand Down
1 change: 1 addition & 0 deletions irmin.opam
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ depends: [
"alcotest" {>= "1.1.0" & with-test}
"alcotest-lwt" {with-test}
"vector" {with-test}
"mdx" {>= "2.0.0" & with-test}
"odoc" {(< "2.0.1" | > "2.0.2") & with-doc} # See https://github.com/ocaml/odoc/issues/793
]

Expand Down