gasche/manual-ocamlbuild

A new reference manual for the ocamlbuild tool

This repository used to hold the up-to-date version of my draft for a new OCamlbuild manual. The manual was since merged in the ocamlbuild repository, and can be found there:

https://github.com/ocaml/ocamlbuild/blob/master/manual/manual.adoc

The present repository still has a pull-request and some issues that remain to be ported to the new repository.

manual-ocamlbuild's Issues

explain .itarget/.otarget more

There is just one sentence explaining these targets, and it only says what .itarget is for, not .otarget.

Confusingly, these extensions are used in the example explaining dynamic dependencies. So one gets the impression that these are not supported by any builtin rules. At the least that example should end by saying "by the way this rule is already provided, we're just showing how you could implement it yourself". But that doesn't seem right either. The example specifically builds symlinks, which isn't what the builtin rule is supposed to do. So it's confusing; the example shouldn't reuse extensions that builtin rules do something different with.

Finally, is there builtin support for this extension or am I using it wrong?

$ cat a.ml 
let () = Printf.printf "hello\n"

$ cat foo.itarget 
a.byte

$ ocamlbuild foo.itarget 
Finished, 0 targets (0 cached) in 00:00:00.

$ tree .
.
├── _build
│   ├── _digests
│   ├── _log
│   └── foo.itarget
├── a.ml
└── foo.itarget

1 directory, 5 files

I was expecting a.byte to get built.

Is it possible to control where ocamlbuild outputs the binary symlink?

For example, $ ocamlbuild program.native will output program.native in the cwd. Is it possible to tell ocamlbuild to create that symlink elsewhere? E.g. suppose that I have a binaries dir where I want the symlinks to be outputted.

Merging the new manual with the new ocamlbuild repo

A question and not an issue, but are there plans/timeline to merge this manual with the newly created separate ocamlbuild repo? You've made tremendous progress on this manual (Thank you!) and I think trying to keep the two projects in sync would be valuable, though I can imagine arguments for keeping them separate.

Examples we should have in the documentation

I'm creating this issue to keep track of various minimal self-contained examples we should have in the documentation, besides the one kindly contributed by @lindig in #13 , because they capture common use-cases. If someone is willing to contribute something to this documentation, please feel free to send a pull-request with one of those examples -- and a little text in the "Examples" section of the introduction.

-cflags, -lflags

those are very helpful flags that are missing explanations in the doc.
I was looking for flambda flags, did not find them, and then recalled there was a way to use not supported flags, using -cflags and -lflags.

Outline

In editing and using this manual I think it is important to get agreement on the layout or outline of each section. In particular, a way of addressing questions such as:

• What are the major sections of the manual?
• What belongs in what section?
• What level of detail to use in the respective sections?

I'll try to give brief answers to the above as a starting point for discussion.

Major Sections:

0. Table of contents (not really a 'section)
1. Introduction
2. Reference
3. Appendix (Index, Glossary?, FAQ?)

Description of sections:

• Intro: A fast and readable tour that describes the features of ocamlbuild. Light on details.
• Reference: Provide a description of how to use ocamlbuild. Heavier on the details, but in an ordered (TBD) way.
• Appendix: Tables and indices that can be almost used as documentation.

new optimization tags for flambda

-Oclassic, -O2 etc. should these be added to the docs? or should this issue go to ocamlbuild main?

how to split plugin into multiple files

Say I want this:

$ cat my_build_lib.ml 
let x = 42

$ cat myocamlbuild.ml 
let x = My_build_lib.x

Now, how can I compile the plugin?

how to create files outside of _build

I'm writing a rule like this:

rule ".merlin"
  ~prod:".merlin"
  (fun env _ -> Echo (["S ./src/**"], ".merlin"))

which produces the file _build/.merlin, but we want .merlin in the root of our repo. I tried using Pathname.pwd but that doesn't seem to help. I'm also not using env, but AFAICT that only expands variable names so it isn't relevant.

(I realize my issues are questions, but hopefully they suggest documentation improvements so are relevant to this repo.)

how to use package during plugin compilation

$ cat myocamlbuild.ml 
let x = 42

$ ocamlbuild -just-plugin -plugin-tag "package(opam-lib)"
Warning: tag "package" does not expect a parameter, but is used with parameter "opam-lib"
Finished, 1 target (0 cached) in 00:00:00.

The package tag does take a parameter, so I'm confused.

Example of custom utop build

We should have an explicit example of custom utop build such as this one.

how to mimic _tags file within myocamlbuild.ml

Within myocamlbuild.ml, how can I apply some tags to files matching a filter.

I know the recommended way of doing this is to define an _tags file, but I don't want to because:

• It's just one more file cluttering my source directory.
• I want to use the information that would go into it in other places also. For instance, I'd like to define a rule to generate a .merlin file. Thus, I need the list of packages my project uses within myocamlbuild.ml.
• I'd rather just use OCaml as my configuration language.

I tried mutating Options.tags, but I'm not sure that's the right variable to change and I don't know how to do this selectively on files matching a pattern.

list of available tags

just as a general feedback on what i found missing in the ocamlbuild documentation personally: i wanted to quickly write a _tags file to state the necessary packages and maybe to switch between debugging builds and regular ones. i remember being frustrated at not finding a good quick overview of all available tags in a prominent place. it would be good to have that.

Restrict to packed usage.

Suppose that I'm creating some packed module $ cat X.mlpack

A
B

Is it possible to somehow make A and B invisible from outside the pack. The purpose of this is to be able to create A (outside the pack) and be able to access X.A

`-plugin-tag` not available on my ocamlbuild

I'm running OCaml 4.00.1 and ocamlbuild does not recognize this command line flag which is documented in the section describing myocamlbuild.ml.

Is this a new feature not yet available in the current version of ocamlbuild?

Is there any reason to no integrate this in the ocamlbuild project ?

and can I get a stable URL before I start linking to it ?

Provide a Unix manual page

OCamlbuild is part of the OCaml distribution that in general provides Unix manual pages for its command line tools. OCamlbuild provides too much functionality to document it exhaustively in a manual page but a short page that explains its purpose and points to the manual would be appropriate. I'm happy to write such a manual page if there is consensus that this is a good idea. As an alternative, we could try to automatically convert the markdown documentation into a manual page but I am not convinced that this is worth the effort.

Syntax for union patterns: {..} or \{..\}?

The manual presents union patterns (with curly braces) as requiring an escape slash:

<td><code>{ p1, p2, ... }</code> (union)</td>
<td><code>toto.\{ml,mli\}</code></td>

Is this correct?

Document invocation, options, and target arguments

OCamlbuild has a a large number of options that are not covered by the manual. The --help flag does a good job explaining them, so maybe it would be good enough for now to refer to it. OCamlbuild accepts multiple targets. It could be important to document in what order they are built as later steps might overwrite files from earlier steps. A section like Invocation could cover the command line interface in the reference section.