Anil Madhavapeddy 8 months ago
parent
commit
0c9ea17841

+ 1 - 0
.ocamlformat

@@ -0,0 +1 @@
+version=0.20.1

+ 31 - 45
book/platform/README.md

@@ -213,6 +213,7 @@ You can also find the built executable in `_build/default/bin/main.exe`.
 
 
 ```sh dir=examples/correct/hello
+$ dune build
 $ dune exec -- bin/main.exe
 Hello World
 ```
@@ -351,23 +352,15 @@ As you develop more OCaml code, you'll find it convenient to have it
 formatted to a common style.  The `ocamlformat` tool can help you do
 this easily from within VSCode.
 
-<!-- TODO yminsky: what's the pattern here? Does ocamlformat support -->
-<!-- multiple versions of its formatting logic concurrently?  If I -->
-<!-- have multiple codebases with the same opam switch but different -->
-<!-- desired ocamlformat versions, am I screwed?  Or do you install -->
-<!-- multiple parallel ocamlformats?  If one ocamlformat supports -->
-<!-- multiple versions, shouldn't we just install the latest -->
-<!-- ocamlformat, rather than install 0.19.0 in particular?    -->
-
 ```skip
-$ echo 'version=0.19.0' > .ocamlformat
-$ opam install ocamlformat.0.19.0
+$ echo 'version=0.20.1' > .ocamlformat
+$ opam install ocamlformat.0.20.1
 ```
 
 The `.ocamlformat` file controls the autoformatting options available,
 and fixes the version of the tool that is used. You can upgrade to a
 newer ocamlformat version whenever you want, but it is a manual
-process to avoid an upstream release autoreformatting your project
+process to avoid an upstream release auto-reformatting your project
 code without your intervention.  You can examine the formatting
 options via `ocamlformat --help` -- most of the time the defaults
 should be fine.
@@ -386,49 +379,39 @@ testing chapter.
 
 ## Publishing your code online
 
-With your IDE set up you'll quickly develop useful OCaml code and want
-to share it with others.  We'll now go through how to define opam
-packages, set up continuous integration and publish your code.
+With your IDE all set up you'll quickly develop useful OCaml code and
+want to share it with others.  We'll now go through how to define
+opam packages, set up continuous integration and publish your code.
 
 ### Defining opam packages
 
 The only metadata file that is really _required_ to participate in the
 open-source OCaml ecosystem is an `opam` file in your source tree.
-Each `opam` file defines an *opam package* -- a collection of OCaml
+Each `opam` file defines a *package* -- a collection of OCaml
 libraries and executable binaries or application data.  Each opam
 package can define dependencies on other opam packages, and includes
-build and testing directions for your project. The `hello.opam` file
-in our sample project is quite easy to read:
-
-<!-- $MDX file=examples/correct/hello/hello.opam -->
-```
-
-```
+build and testing directions for your project. 
 
-The fields in here all represent project metadata ranging from textual
-descriptions, to project URLs, to other opam package dependencies.  A
-collection of `opam` files can be stored in an *opam repository* to
+A collection of `opam` files can be stored in an *opam repository* to
 create a package database, with a central one for the OCaml ecosystem
 available at <https://github.com/ocaml/opam-repository>.  The official
 (but not exclusive) tool used for manipulating `opam` files is the
 eponymous [opam package manager](https://opam.ocaml.org) that we've
 been using throughout this book.
 
+The `hello.opam` file in our sample project is currently empty, but we
+can generate it next using dune.
+
 ### Generating project metadata from dune
 
 You don't need to write the opam file by hand -- instead, we can use
 define our project metadata using the dune build system and have it
-autogenerated for us.  We've already been using the `dune` build tool
-from back in [Files Modules And
-Programs](files-modules-and-programs.html#files-modules-and-programs){data-type=xref}. We're
-now going to look at how to configure your project for use with dune.
-
-The root directory of an OCaml project built by dune has a
-`dune-project` file that defines the project metadata. In our hello
-world example, it starts with:
+autogenerated for us. The root directory of an OCaml project built by
+dune has a `dune-project` file that defines the project metadata. In our
+example project, it starts with:
 
 ```scheme
-(lang dune 2.0)
+(lang dune 2.9)
 ```
 
 The line above is the version of the syntax used in your build files,
@@ -450,10 +433,10 @@ The rest of the `dune-project` file defines other useful project metadata:
 (generate_opam_files true)
 ```
 
-The fields here should look familiar -- they were also present in the
-`hello.opam` file above.  That's because dune can generate the opam
-packaging metadata files for you and avoid duplication.  Go ahead and
-edit the metadata above, and then build the project with:
+The fields in here all represent project metadata ranging from textual
+descriptions, to project URLs, to other opam package dependencies.
+Go ahead and edit the metadata above to reflect your own details, and
+then build the project:
 
 ```skip
 $ dune build
@@ -504,6 +487,7 @@ and opam packages in your dune files match up, and offer to fix them
 up if it spots a mismatch. `opam lint` runs additional checks on the
 opam files within your project.
 
+
 ### Setting up Continuous Integration
 
 Once you have your project metadata defined, it's a good time to begin
@@ -557,25 +541,27 @@ earlier on all those different operating systems as well.  You can do
 an awful lot of customisation of these continuous integration
 workflows, so refer to the online documentation for more options.
 
-### Conventions
+### Other conventions
 
 There are a few other files you may also want to add to a project
 to match common conventions:
 
-- the `Makefile` contains targets for common actions such as `all`,
-  `build`, `test` or `clean`.  It's useful to read through this to see
-  which underlying OCaml tools are being invoked.
+- a `Makefile` contains targets for common actions such as `all`,
+  `build`, `test` or `clean`. While you don't need this when using
+  VSCode, some other operating system package managers might benefit
+  from having one present.
 - the `LICENSE` defines the terms under which your code is made
-  available, and defaults to the permissive ISC license.
+  available. Our example defaults to the permissive ISC license, and
+  this is generally a safe default unless you have specific plans
+  for your project.
 - a `README.md` is a Markdown-formatted introduction to your library
   or application.
-- the `.gitignore` file contains the patterns for generated files from
+- a `.gitignore` file contains the patterns for generated files from
   the OCaml tools so that they can be ignored by the Git version
   control software.  If you're not familiar with using Git, look over
   one of the tutorials one such as GitHub's [git hello
   world](https://guides.github.com/activities/hello-world/).
 
-
 ### Releasing your code into the opam repository
 
 Once your continuous integration is passing, you are all set to try to

+ 15 - 0
book/platform/examples/correct/hello/dune-project

@@ -1,2 +1,17 @@
 (lang dune 2.9)
 (name hello)
+(documentation "https://username.github.io/hello/")
+(source (github username/hello))
+(license ISC)
+(authors "Your name")
+(maintainers "Your name")
+(generate_opam_files true)
+
+(package
+ (name hello)
+ (synopsis "A short description of the project")
+ (description "A short description of the project")
+ (depends
+  (ocaml (>= 4.08.0))
+  (odoc :with-doc)))
+

+ 32 - 0
book/platform/examples/correct/hello/hello.opam

@@ -0,0 +1,32 @@
+# This file is generated by dune, edit dune-project instead
+opam-version: "2.0"
+synopsis: "A short description of the project"
+description: "A short description of the project"
+maintainer: ["Your name"]
+authors: ["Your name"]
+license: "ISC"
+homepage: "https://github.com/username/hello"
+doc: "https://username.github.io/hello/"
+bug-reports: "https://github.com/username/hello/issues"
+depends: [
+  "dune" {>= "2.9"}
+  "ocaml" {>= "4.08.0"}
+  "odoc" {with-doc}
+]
+build: [
+  ["dune" "subst"] {dev}
+  [
+    "dune"
+    "build"
+    "-p"
+    name
+    "-j"
+    jobs
+    "--promote-install-files=false"
+    "@install"
+    "@runtest" {with-test}
+    "@doc" {with-doc}
+  ]
+  ["dune" "install" "-p" name "--create-install-files" name]
+]
+dev-repo: "git+https://github.com/username/hello.git"