Giter Site home page Giter Site logo

manual-ocamlbuild's Introduction

manual-ocamlbuild's People

Contributors

agarwal avatar armael avatar gasche avatar khady avatar lindig avatar rleonid avatar ttamttam avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

manual-ocamlbuild's Issues

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.

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.

-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.

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

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.

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.)

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.

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:

  1. Table of contents (not really a 'section)
  2. Introduction
  3. Reference
  4. 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.

`-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?

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?

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.

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.

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.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.