ocamlpro/drom

drom is a wrapper over opam/dune in an attempt to provide a cargo-like user experience. It can be used to create full OCaml projects with sphinx and odoc documentation. It has specific knowledge of Github and will generate files for Github Actions CI and Github pages.

drom

The drom tool is a wrapper over opam/dune in an attempt to provide a cargo-like user experience. It can be used to create full OCaml projects with sphinx and odoc documentation. It has specific knowledge of Github and will generate files for Github Actions CI and Github pages.

• Website: https://ocamlpro.github.io/drom
• General Documentation: https://ocamlpro.github.io/drom/sphinx
• API Documentation: https://ocamlpro.github.io/drom/doc
• Sources: https://github.com/ocamlpro/drom

Simple Example

You can create a new OCaml project with:

$ drom new my-client --skeleton mini_prg
Creating project "my-client" with skeleton "mini_prg", license "LGPL2"
  and sources in src/my-client:
Creating directory my-client
Using skeleton "program" for package "my-client"
[master (root-commit) 8d83262] Initial commit

└── my-client/
    ├── .drom             (drom state, do not edit)
    ├── .github/
    │   └── workflows/
    │       └── workflow.yml
    ├── .gitignore
    ├── CHANGES.md
    ├── LICENSE.md
    ├── Makefile
    ├── README.md
    ├── drom.toml    <────────── project config EDIT !
    ├── dune
    ├── dune-project
    ├── opam/
    │   └── my-client.opam
    ├── scripts/
    │   ├── after.sh
    │   ├── before.sh
    │   └── copy-bin.sh
    └── src/
        └── my-client/
            ├── dune
            ├── main.ml
            ├── package.toml    <────────── package config EDIT !
            └── version.mlt

This project uses the minimalist mini_prg skeleton, but other skeletons like program or library have more files.

drom's Issues

scripts copied with wrong chmod

scripts from virtual project (before.sh, after.sh, copy-bin.sh) are not executable in a new project

add option `--force` to `drom project`

Currently, if a file has been modified or pre-exists, drom will just print a warning and skip the file. It could be useful to have --force option to overwrite such files.

add `[dependencies]` , `[tools]` and `[fields]` sections in `package.toml`

These sections should always be visible, even when they are empty.
In general, we should improve drom.toml by adding comments to explain what the [dependencies] section there is for (project-wide dependencies) and to use package.toml for package-specific dependencies.
We should also put all the fields of package.toml file in comments so that the user can know what he can define.

'drom package' should infer the current package based on the current working directory

When no package name is specified, the 'drom package' command should try to infer the current package based on the current working directory (by checking if there is a package.toml in the directory or its parent)

Allow default git branch configuration

The GitHub skeleton hardcodes the default branch to master while Github allows the branch to be named something else.
As far as I know, this is an issue only for the workflows which are only triggered when push to master happens.
Drom could have an optional key (git-default-branch?) to allow setting it to something else.

I'd be happy to give it a try if there is some documentation on how variables substitution work in drom.

add prompt fallback when user name or e-mail can't be determined

Here and here, we should ask the user to input the missing value.

We should also add an option to disable it (using e.g. a environment variable) for runs in CI or whatever.

The use case is for people having a commit e-mail provided by GitHub/Gitlab that they set in .git/config after project creation (so we can't find it) but they want a true e-mail address for opam files and the like.

Otherwise we could just tell them to set DROM_EMAIL=... drom new and fail, so they don't have to look for it in the documentation if they can't remember it and it would be much more easy to fix.

Use a better hash function that md5 when publishing opam packages

Dune version

Is it possible to change the dune version in order to use cram tests ?

Update dependencies on the command line

We could have commands like:

drom dep DEP with arguments:

• --package TOTO
• --add
• --remove
• --all
• --version VVV
• --for-test
• --for-doc

The command would update drom.toml and package.toml files, update opam and dune files, and maybe build if --build is provided.

In the case where we share a global switch, pin the package

future - tags

Tags don't seem to be heavily used on opam. Would be nice to facilitate more use. I am not sure how to do this exactly, but this project might hekpt

Error with Toml library

@zapashcanon There is a problem everytime the package.toml file is saved, a newline is added to every multi-line string field starting with """.

See https://github.com/OCamlPro/freeton-ocaml-sdk/blob/e647f5740ac995ba92a844280fcb8f5ba8cba57f/src/ft_lib/package.toml#L58 for example.

This problem was not there before the last change in the Toml library.

Question on desired scope of drom

I have a question about the desired scope of drom. It is not the common case, but sometimes a project has a nontrivial setup step before opam and dune can get started. For example, if more than one opam switch needs to be created (e.g. for multiple compiler versions, or with and without flambda, etc.) and a dune-workspace file needs to be generated using the names of those switches (e.g. to associate build profiles with switches).

I could imagine an extension of drom where a project description could declare several opam switches with differing constraints, and several dune build contexts with the associations between switches and contexts, as well as the dune build profiles. Essentially there are currently 3 distinct notions: opam switch, dune context, dune profile, which can have nontrivial associations between them, and need to be set up in different stages. It would be a user-level simplification if drom could provide a single concept that combines these together and generates the needed metadata for the current tooling.

generate doc in gh-pages with github action instead of storing in git

cool, consider codeberg or notabug

Github makes sense as a default choice. A small minority (<1%) might prefer having a github alternative option, if that fits in the longer term roadmap.

warn on duplicated value in `drom.toml` package section

If a value is in a package.toml we should warn if an equal one is added in a drom.toml file package section.

E.g. when kind = "library" is present in both it should only be in the package.toml file. This should help to catch things like this one.

Add the ability to have sub-projects

This would be useful to e.g. work with git submodules.

"skip" field should be an array of strings

The "skip" field is currently of type string, but it should be an array of strings.

do not write anything until the end to prevent partial state errors

Remove `kind` and `mode`, since skeletons can be used instead.

`drom publish` could be extended to perform the release and use `opam-publish` for final steps

potential feature: tutorial directory configured to use lipsum or mdx

(I'm still studying how it works, so I may have the details wrong)

Consider adding the following as part of new project default:

• a directory called "tutorials"
• inside the directory, populate some starter files for a tutorial similar to https://github.com/lindig/lipsum/tree/master/examples

Feel free to substitute any other project that is similar to lipsum.

build-profile not used

For the js skeletons, we need to set the build-profile to "release" because it changes the js_of_ocaml compiling behaviour (there is no other method to do this in dune).
The build-profile should be propagated to at least the Makefile to do dune build --profile <build-profile>

Error with `drom new`

Using drom new <my-project> I get the following error message:

saroupille@saroupille:/tmp$ drom new my-project
Creating project "my-project" with skeleton "program", license "LGPL2"
  and sources in src/my-project:
Creating directory my-project
Error: Could not parse: toml template at Error in <string> at line 5 at column 17 (position 61): Forbidden escaped char

Here is the version I use:

saroupille@saroupille:~/Git$ opam switch
#  switch                                     compiler                    description
→  default                                    ocaml-system.4.11.1         default
saroupille@saroupille:~/Git$ opam list drom
# Packages matching: (installed | available) & name-match(drom)
# Package  # Installed # Synopsis
drom.0.2.0 0.2.0       The drom tool is a wrapper over opam/dune in an attempt to provide a cargo-like user experience
```#

Spin and Drom integration

Hi!

First off, thanks a lot for your work on Drom, it's really nice to see some initiative to simplify users' workflow and project generation.

I'm especially excited by the project generation part, as I have spent some time thinking about this when developing Spin.

I see a lot of overlaps with Spin and Drom (which is great, because they have been developed independently, so it's a good signal for the need for such a tool). I was wondering how you feel about an integration of the two. The immediate benefit is to provide a single template format for OCaml's community, that Drom, Spin, or any other tool could consume.

Drom has a scope a bit larger than Spin, so I'm tempted to suggest that Drom could use Spin as a library for the project generation part.

Does that seem like a good idea to you? If it does, I'm planning on looping back on Spin in the coming weeks and would gladly integrate any feature you would need for such integration to happen.

Thanks again for all your work 🙂

Do not use OCaml escaping for toml files

authors-as-strings is used to generate the initial toml files, but it uses OCaml escaping, that will not work correctly with Toml files. We should add another substitution that escapes correctly for toml files.

Available on public opam repository?

Looks like a very useful project! The docs say "if drom is available in your opam repository, you can just call: opam install drom" but it doesn't seem to be available on standard opam. Is there a repo that has it?

add bisect_ppx support

The idea would be to have a boolean flag in projects (which can be overridden on a per package basis) to enable bisect_ppx support.

If it is enabled, we should add something like:

(instrumentation (backend bisect_ppx))

to all dune stanzas of the packages.

Once this is done, we can add some code to the deploy-doc GitHub action to run the coverage and put the result in doc/coverage and add a link in the index.html page of the documentation.

I did it by hand in toml to see what it would look like. See :

• homepage with the link to coverage results added
• coverage report generated
• GitHub action code used to generate it

Missing step in Quick Start doc

Working through the Quick Start prompts you to issue the following series of commands:

$ drom new hello_world
$ cd hello_world
$ drom project
$ drom build -y
$ drom run

Command 'drom' not found, did you mean:
...

The last one fails because drom is not installed on the (newly-created by drom) local switch. I resolved this with an opam install drom in between, very simple, but maybe some people would be confused.

Also I'm not exactly sure what the recommended solution is. If it is to have drom on the local switch maybe it should be included in the package list by default?

Add support for "skip" in package.toml

At the moment, "skip" is only supported in drom.toml.
It would be useful to also have it in package.toml (possibly with paths relative to the directory containing the .toml file).

Add option `--scan DIR` to `drom project` to scan for `package.toml` and add them

Add option to install in global opam switchs instead of `_opam`

Add something like drom install --global 4.10.0 or drom install --global current

Add source files on the command line

Maybe something like:

drom package toto --new-file toto.ml

that would create the file with the correct header. If the new file is a .mll or .mly, the dune file is updated too.

Improve opam file generation

ocaml/opam-repository#17730 (comment)

automatically add package dirs to `dune-dirs`

The (dirs ...) stanza in the toplevel dune should contain the top dirs of all packages.

Install more packages when `drom build` is executed

When I execute drom build -y for the first time, it sets up a new local opam repository. In this repository, merlin, drom, tuareg, ocamlformat are not installed, maybe they should be installed, no?

publishing virtual packages

I don't understand how to publish virtual packages with drom. Virtual skeleton seems to be an information only used by drom and not propagated to opam as no .opam file is generated nor published when drom publish is used. Can we create opam virtual packages through drom or should we manually write the .opam file ? The latter solution seems quite ugly since all needed informations are in the dune-project generated by drom but we can't even use dune to generate the missing .opam files for generate_opam_files is set to false.

drom fields in bracket condition

add the possibility to write bracket conditions with various drom fields

Skeleton project with no package

Is there any way to write a skeleton for a project which does not automatically generate a package inside src with the name of the project? Thanks!

Replace `windows-ci` by a list `ci-systems`

Users may want to also disable CI on macos or linux. So, replace windows-ci by:

ci-systems = [ "ubuntu-latest", "macos-latest", "windows-latest" ]

by default. Users may choose to remove/add systems in the list.

Add `drom init` as an alias for `drom new PROJECT --inplace`

The name of the project would be inferred from the name of the directory.
Other informations could be inferred from the dune-project file if present and no drom.toml.

`version.ml` should be created dynamically by `dune`

It would allow this file to contain the latest git commit and such information.

use user config for ocamlformat and ocpindent if it exists

see #7

failed install : shift command

opam install .

[drom.0.2.2] synchronised (no changes)
[drom_lib.0.2.2] synchronised (no changes)
The following actions will be performed:
  ↻ recompile drom_lib 0.2.2*
  ↻ recompile drom     0.2.2*
===== ↻ 2 =====

<><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><><><>
[ERROR] The compilation of drom_lib.0.2.2 failed at "sh -c ./scripts/before.sh build drom_lib".

#=== ERROR while compiling drom_lib.0.2.2 =====================================#
# context     2.1.0~beta2 | linux/x86_64 | ocaml-base-compiler.4.11.1 | pinned(git+file:///home/max/origin/drom#master#df489a24)
# path        ~/.opam/4.11.1/.opam-switch/build/drom_lib.0.2.2
# command     /bin/sh -c ./scripts/before.sh build drom_lib
# exit-code   2
# env-file    ~/.opam/log/drom_lib-7020-0a5907.env
# output-file ~/.opam/log/drom_lib-7020-0a5907.out
### output ###
# ./scripts/before.sh: 24: shift: can't shift that many



<><> Error report <><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>
┌─ The following actions failed
│ λ build drom_lib 0.2.2
└─ 
╶─ No changes have been performed

An `opam` file for a `virtual` package should not contain build instructions

add hooks on various sub-commands

Version 0.2.1 introduces a hook scripts/before-sphinx.sh that is ran before calling sphinx-builder. It can be used for example to generate documentation files. Such hooks could be interesting to add for other commands:

• drom build could run scripts/before-build.sh after installing the _opam switch (could be used to run ./configure) and scripts/after-build.sh after the build
• drom test could run scripts/before-test.sh and scripts/after-test.sh
• drom install could run scripts/before-install.sh and scripts/after-install.sh
• drom uninstall could run scripts/before-uninstall.sh and scripts/after-uninstall.sh
• drom publish could run scripts/after-publish.sh $OPAM_REPO_DIR

Specify pinned package

If I start a new project which requires a modified version of a package A which is not the official one on opam. Is there a way to specify that I want to pin A in drom.toml file? Right now, I guess the solution is to do opam pin manually.

drom project overwrites .ocp-indent if it's the default one

Hi,

Running drom project in an already existing drom project will overwrite the .ocp-indent existing file if it is the default one and the user has one in "$XDG_CONFIG_HOME/ocp/.

That's annoying in the following case:

• I want to contribute to e.g. OCamlPro/drom (which use the default .ocp-indent file)
• I change something in drom.toml and thus, I run drom project to update everything
• The .ocp-indent file is replaced by the one I have in "$XDG_CONFIG_HOME/ocp/, which is something I didn't wanted

I guess we should either:

• copy the file in "$XDG_CONFIG_HOME/ocp/ only if there isn't one in the current drom project (and eventually, add an option to drom project which allows the user to copy the file anyway, but that shouldn't be the default !)
• ask the user if he wants to overwrite the file (with default option being not to overwrite it)

I'm willing to implement any of it, but I'd like to discuss it first.

using crunch instead of the current system to embed skel files

We could use crunch to embed all the skeletons files, which should be much easier to deal with than the current system. Here's a minimal example of using crunch to embed some files.

I'm willing to implement it, but let's discuss it first.

[Help] How to create a native shared library using drom?

Hi team,

I was wondering how can I use drom to create a shared_object?

I tried the following steps to achieve this goal.

• I created a project

drom new drom_program_1 --skeleton program

• Updated the dune file for the src/drom_program_1/dune

; generated by drom from package skeleton 'driver'
(executable
  (name main)
  (public_name drom_program_1)
  (package drom_program_1)
  (libraries drom_program_1_lib )
  (modes native shared_object)
  
  )


(documentation
  (package drom_program_1))

Thanks for your help!