gasche / manual-ocamlbuild Goto Github PK
View Code? Open in Web Editor NEWA new reference manual for the ocamlbuild tool
License: Other
A new reference manual for the ocamlbuild tool
License: Other
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.
$ 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.
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.
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.)
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.
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.
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.
-Oclassic, -O2 etc. should these be added to the docs? or should this issue go to ocamlbuild main?
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.
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?
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.
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?
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:
.merlin
file. Thus, I need the list of packages my project uses within myocamlbuild.ml
.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.
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
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.
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?
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:
I'll try to give brief answers to the above as a starting point for discussion.
Major Sections:
Description of sections:
and can I get a stable URL before I start linking to it ?
We should have an explicit example of custom utop build such as this one.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.