Sub-commands and Arguments
Common arguments to all sub-commands:
-qor--quietSet verbosity level to 0-vor--verboseIncrease verbosity level
Overview of sub-commands:
build
Build a project
build-deps
Install build dependencies only
clean
Clean the project from build files
config
Read/write configuration
dep (since version 0.2.1)
Manage dependency of a package
dev-deps
Install dev dependencies (odoc, ocamlformat, merlin, etc.)
doc
Generate all documentation (API and Sphinx)
fmt
Format sources with ocamlformat
headers
Check all headers in project
install
Build & install the project in the project opam switch
list (since version 0.4.0)
List available project or packages skeletons
new
Create a new project
odoc
Generate API documentation using odoc in the _drom/docs/doc directory
opam-plugin (since version 0.2.1)
Install drom as an opam plugin (called by 'opam drom')
package
Manage a package within a project
project
Update an existing project
promote
Promote detected changes after running drom test or drom fmt
publish
Update opam files with checksums and copy them to a local opam-repository for publication
run
Execute the project
sphinx
Generate documentation using sphinx
test
Run tests
toml
Read TOML files and print them back on stdout
top
Run the ocaml toplevel
tree
Display a tree of dependencies
uninstall
Uninstall the project from the project opam switch
update
Update packages in switch
main.exe build
Build a project
DESCRIPTION
This command performs the following actions:
1. Create a local opam switch. The argument –switch SWITCH can be used to make the local switch a link to a global switch. The argument –local can be used to force a local switch to be created.
2. Check that the OCaml version is at least the min-edition specified in the project. If OCaml is not installed, use the –edition VERSION argument or the edition field specified in the project to install OCaml.
3. Install all the dependencies in the opam switch. If the argument –locked was specified, use the ${package}-deps.opam.locked file in the project to get exact dependencies.
4. Build the project by calling opam exec – dune build @install
5. If build was ok, copy executable in the top directory of the project
USAGE
main.exe build [OPTIONS]
Where options are:
--edition VERSIONUse this OCaml edition--localCreate a local switch instead of using a global switch--profile PROFILEBuild profile to use--switch OPAM_SWITCHUse global switch SWITCH instead of creating a local switch--upgradeUpgrade project files from drom.toml-yor--yesReply yes to all questions
main.exe build-deps
Install build dependencies only
USAGE
main.exe build-deps [OPTIONS]
Where options are:
--edition VERSIONUse this OCaml edition--localCreate a local switch instead of using a global switch--profile PROFILEBuild profile to use--switch OPAM_SWITCHUse global switch SWITCH instead of creating a local switch--upgradeUpgrade project files from drom.toml-yor--yesReply yes to all questions
main.exe clean
Clean the project from build files
USAGE
main.exe clean [OPTIONS]
Where options are:
--distcleanAlso remove _opam/ (local switch) and _drom/
main.exe config
Read/write configuration
DESCRIPTION
This command is useful to read/write drom configuration
EXAMPLE
The following displays the list of project skeletons:
drom config --project-skeletons
USAGE
main.exe config [OPTIONS]
Where options are:
--no-fetch-sharePrevent fetching updates from the share repo (in particular without network connection--package-skeletonsList available package skeletons--project-skeletonsList available project skeletons--reclone-shareReclone share repository--share-repo SHARE_REPOSet the repository URL of the share database (use ‘default’ for default repo)--share-version SHARE_VERSIONSet the version of share database (use ‘latest’ for latest version)
main.exe dep (since version 0.2.1)
Manage dependency of a package
DESCRIPTION
Add, remove and modify dependencies from drom.toml and package.toml files.
If the argument –package is not specified, the dependency is added project-wide (i.e. for all packages), updating the drom.toml file.
If the argument –package is provided, the dependency is added to the package.toml file for that particular package.
Dependencies can be added –add, removed –remove or just modified. The –tool argument should be used for tool dependencies, i.e. dependencies that are not linked to the library/program.
If no modification argument is provided, the dependency is printed in the terminal. Modification arguments are –ver VERSION for the version, –lib LIBNAME for the dune library name, –doc BOOL for documentation deps and –test BOOL for test deps.
EXAMPLE
drom dep --package drom_lib --add ez_cmdliner --ver ">0.1"
drom dep --package drom_lib --remove ez_cmdliner
drom dep --add --tool odoc --ver ">1.0 <3.0" --doc true
VERSION SPECIFICATION
The version specified in the –ver VERSION argument should follow the following format:
1. Spaces are used to separate a conjunction of version constraints.
2. An empty string is equivalent to no version constraint.
3. Constraints are specified using a comparison operation directly followed by the version, like >1.2 or <=1.0.
4. A semantic version like 1.2.3 is equivalent to the constraints >=1.2.3 and <2.0.0.
USAGE
main.exe dep DEPENDENCY [OPTIONS]
Where options are:
DEPENDENCYName of dependency--addAdd as new dependency--create BOOLChange project creation status--cross TARGETBuild opam packages for cross-compilation (TARGET=windows|osx)--diffPrint a diff of user-modified files that are being skipped--doc BOOLWhether dependency is only for doc--edition OCAMLVERSIONSet project default OCaml version-for--forceForce overwriting modified files (otherwise, they would be skipped)--lib LIBNAMEDependency should have this libname in dune--min-edition OCAMLVERSIONSet project minimal OCaml version--no-fetch-sharePrevent fetching updates from the share repo (in particular without network connection--opt BOOLWhether dependency is optional or not--package PACKAGEAttach dependency to this package name--promote-skipPromote user-modified files to skip field--reclone-shareReclone share repository--removeRemove this dependency--share-repo SHARE_REPOSet the repository URL of the share database (use ‘default’ for default repo)--share-version SHARE_VERSIONSet the version of share database (use ‘latest’ for latest version)--skip FILEAdd FILE to skip list--test BOOLWhether dependency is only for tests--toolDependency is a tool, not a library--unskip FILERemove FILE from skip list--ver VERSIONDependency should have this version
main.exe dev-deps
Install dev dependencies (odoc, ocamlformat, merlin, etc.)
USAGE
main.exe dev-deps [OPTIONS]
Where options are:
--edition VERSIONUse this OCaml edition--localCreate a local switch instead of using a global switch--profile PROFILEBuild profile to use--switch OPAM_SWITCHUse global switch SWITCH instead of creating a local switch--upgradeUpgrade project files from drom.toml-yor--yesReply yes to all questions
main.exe doc
Generate all documentation (API and Sphinx)
USAGE
main.exe doc [OPTIONS]
Where options are:
--edition VERSIONUse this OCaml edition--localCreate a local switch instead of using a global switch--profile PROFILEBuild profile to use--switch OPAM_SWITCHUse global switch SWITCH instead of creating a local switch--upgradeUpgrade project files from drom.toml--viewOpen a browser on the documentation-yor--yesReply yes to all questions
main.exe fmt
Format sources with ocamlformat
USAGE
main.exe fmt [OPTIONS]
Where options are:
--auto-promotePromote detected changes immediately--edition VERSIONUse this OCaml edition--localCreate a local switch instead of using a global switch--profile PROFILEBuild profile to use--switch OPAM_SWITCHUse global switch SWITCH instead of creating a local switch--upgradeUpgrade project files from drom.toml-yor--yesReply yes to all questions
main.exe headers
Check all headers in project
USAGE
main.exe headers [OPTIONS]
Where options are:
--add-default HEADER_IDAdd this header as the default for these files--from HEADER_IDReplace this header--replace SRC:DSTReplace header SRC by header DST--replace-by HEADER_IDReplace by this header--skip HEADER_IDskip this header when printing headers
main.exe install
Build & install the project in the project opam switch
USAGE
main.exe install PACKAGES [OPTIONS]
Where options are:
PACKAGESSpecify the list of packages to install--edition VERSIONUse this OCaml edition--localCreate a local switch instead of using a global switch--profile PROFILEBuild profile to use--switch OPAM_SWITCHUse global switch SWITCH instead of creating a local switch--upgradeUpgrade project files from drom.toml-yor--yesReply yes to all questions
main.exe list (since version 0.4.0)
List available project or packages skeletons
DESCRIPTION
List available project or packages skeletons
USAGE
main.exe list ARGUMENTS [OPTIONS]
Where options are:
ARGUMENTSUse ‘projects’ or ‘packages’ to display corresponding skeletons--no-fetch-sharePrevent fetching updates from the share repo (in particular without network connection--reclone-shareReclone share repository--share-repo SHARE_REPOSet the repository URL of the share database (use ‘default’ for default repo)--share-version SHARE_VERSIONSet the version of share database (use ‘latest’ for latest version)
main.exe new
Create a new project
DESCRIPTION
This command creates a new project, with name PROJECT in a directory PROJECT (unless the –inplace argument was provided).
EXAMPLE
The following command creates a project containing library my_lib in src/my_lib:
drom new my_lib --skeleton library
The following command creates a project containing a library hello_lib in src/hello_lib and a program hello in src/hello calling the library:
drom new hello --skeleton program
USAGE
main.exe new PROJECT [OPTIONS]
Where options are:
PROJECTName of the project--create BOOLChange project creation status--diffPrint a diff of user-modified files that are being skipped--dir DIRECTORYDir where package sources are stored (src by default)--edition OCAMLVERSIONSet project default OCaml version-for--forceForce overwriting modified files (otherwise, they would be skipped)--inplaceCreate project in the the current directory--libraryProject contains only a library--min-edition OCAMLVERSIONSet project minimal OCaml version--no-fetch-sharePrevent fetching updates from the share repo (in particular without network connection--programProject contains only a program--promote-skipPromote user-modified files to skip field--reclone-shareReclone share repository--share-repo SHARE_REPOSet the repository URL of the share database (use ‘default’ for default repo)--share-version SHARE_VERSIONSet the version of share database (use ‘latest’ for latest version)--skeleton SKELETONCreate project using a predefined skeleton or one specified in ~/.config/drom/skeletons/--skip FILEAdd FILE to skip list--unskip FILERemove FILE from skip list--virtualPackage is virtual, i.e. no code
main.exe odoc
Generate API documentation using odoc in the _drom/docs/doc directory
USAGE
main.exe odoc [OPTIONS]
Where options are:
--edition VERSIONUse this OCaml edition--localCreate a local switch instead of using a global switch--profile PROFILEBuild profile to use--switch OPAM_SWITCHUse global switch SWITCH instead of creating a local switch--upgradeUpgrade project files from drom.toml--viewOpen a browser on the documentation-yor--yesReply yes to all questions
main.exe opam-plugin (since version 0.2.1)
Install drom as an opam plugin (called by ‘opam drom’)
DESCRIPTION
This command performs the following actions:
1. Install drom executable in $OPAMROOT/plugins/bin/opam-drom
2. Install drom share files in $OPAMROOT/plugins/opam-drom, removing former files
USAGE
main.exe opam-plugin [OPTIONS]
Where options are:
--removeRemove drom as an opam plugin
main.exe package
Manage a package within a project
USAGE
main.exe package PACKAGE [OPTIONS]
Where options are:
PACKAGEName of the package--create BOOLChange project creation status--diffPrint a diff of user-modified files that are being skipped--dir DIRECTORYDir where package sources are stored (src by default)--editEdit package.toml description with EDITOR--edition OCAMLVERSIONSet project default OCaml version-for--forceForce overwriting modified files (otherwise, they would be skipped)--libraryPackage is a library--min-edition OCAMLVERSIONSet project minimal OCaml version--new SKELETONAdd a new package to the project with skeleton NAME--new-file FILENAME(since version 0.2.1) Add new source file--no-fetch-sharePrevent fetching updates from the share repo (in particular without network connection--programPackage is a program--promote-skipPromote user-modified files to skip field--reclone-shareReclone share repository--remove(since version 0.2.1) Remove a package from the project--rename NEW_NAMERename secondary package to a new name--skip FILEAdd FILE to skip list--unskip FILERemove FILE from skip list--virtualPackage is virtual, i.e. no code
main.exe project
Update an existing project
DESCRIPTION
This command is used to regenerate the files of a project after updating its description.
With argument –upgrade, it can also be used to reformat the toml files, from their skeletons.
USAGE
main.exe project [OPTIONS]
Where options are:
--create BOOLChange project creation status--diffPrint a diff of user-modified files that are being skipped--editEdit project description--edition OCAMLVERSIONSet project default OCaml version-for--forceForce overwriting modified files (otherwise, they would be skipped)--libraryProject contains only a library. Equivalent to –skeleton library--min-edition OCAMLVERSIONSet project minimal OCaml version--no-fetch-sharePrevent fetching updates from the share repo (in particular without network connection--programProject contains a program. Equivalent to –skeleton program. The generated project will be composed of a library package and a driver package calling the Main.main of the library.--promote-skipPromote user-modified files to skip field--reclone-shareReclone share repository--share-repo SHARE_REPOSet the repository URL of the share database (use ‘default’ for default repo)--share-version SHARE_VERSIONSet the version of share database (use ‘latest’ for latest version)--skeleton SKELETONCreate project using a predefined skeleton or one specified in ~/.config/drom/skeletons/--skip FILEAdd FILE to skip list--unskip FILERemove FILE from skip list--upgradeForce upgrade of the drom.toml file from the skeleton--virtualPackage is virtual, i.e. no code. Equivalent to –skeleton virtual.
main.exe promote
Promote detected changes after running drom test or drom fmt
USAGE
main.exe promote [OPTIONS]
Where options are:
--edition VERSIONUse this OCaml edition--localCreate a local switch instead of using a global switch--profile PROFILEBuild profile to use--switch OPAM_SWITCHUse global switch SWITCH instead of creating a local switch--upgradeUpgrade project files from drom.toml-yor--yesReply yes to all questions
main.exe publish
Update opam files with checksums and copy them to a local opam-repository for publication
DESCRIPTION
Before running this command, you should edit the file $HOME/.config/drom/config and set the value of the opam-repo option, like:
[user]
author = "John Doe <john.doe@ocaml.org>"
github-organization = "ocaml"
license = "LGPL2"
copyright = "OCamlPro SAS"
opam-repo = "/home/john/GIT/opam-repository"
Alternatively, you can run it with option –opam-repo REPOSITORY.
In both case, REPOSITORY should be the absolute path to the location of a local git-managed opam repository.
drom publish will perform the following actions:
1. Download the source archive corresponding to the current version
2. Compute the checksum of the archive
3. Copy updated opam files to the git-managed opam repository. During this operation, comment lines,
version:andnamelines are removed to conform to opam-repository policies.
Note that, prior to calling drom publish, you should update the opam-repository to the latest version of the master branch:
git checkout master
git pull ocaml master
Once the opam files have been added, you should push them to your local fork of opam-repository and create a merge request:
cd ~/GIT/opam-repository
git checkout -b z-$(date --iso)-new-package-version
git add packages
git commit -a -m "New version of my package"
git push
To download the project source archive, drom publish will either use the archive URL of the drom.toml file, or the Github URL (if the github-organization is set in the project), assuming in this later case that the version starts with ‘v’ (like v1.0.0). Two substitutions are allowed in archive: ${version} for the version, ${name} for the package name.
USAGE
main.exe publish [OPTIONS]
Where options are:
-for--forceOverwrite existing files--md5Use md5 instead of sha256 for checksums--opam-repo DIRECTORYPath to local git-managed opam-repository. The path should be absolute. Overwrites the value opam-repo from $HOME/.config/drom/config
main.exe run
Execute the project
DESCRIPTION
This command performs the following actions:
1. Decrease verbosity level to display nothing during build
2. Build the project packages (see drom build for info).
3. Call opam exec – drun exec – [PACKAGE] [ARGUMENTS], where [PACKAGE] is either the package name specified with the -p PACKAGE argument or the main package of the project if it is a program, [ARGUMENTS] are the arguments specified with drom run
USAGE
main.exe run ARGUMENTS [OPTIONS]
Where options are:
ARGUMENTSArguments to the command--edition VERSIONUse this OCaml edition--localCreate a local switch instead of using a global switch-p PACKAGEPackage to run--profile PROFILEBuild profile to use--switch OPAM_SWITCHUse global switch SWITCH instead of creating a local switch--upgradeUpgrade project files from drom.toml-yor--yesReply yes to all questions
main.exe sphinx
Generate documentation using sphinx
DESCRIPTION
This command performs the following actions:
1. Build the project, installing dev dependencies if not done yet (see drom build and drom dev-deps for more info).
2. If a file scripts/before-sphinx.sh exists, run it
3. Build Sphinx documentation using the command sphinx-build sphinx _drom/docs/${sphinx-target}, where ${sphinx-target} is the sphinx-target field in the project description, or sphinx by default. Documentation source files are expected to be found in the top sphinx/ directory.
4. If the argument –view was specified, open a browser on the newly generated documentation
USAGE
main.exe sphinx [OPTIONS]
Where options are:
--edition VERSIONUse this OCaml edition--localCreate a local switch instead of using a global switch--profile PROFILEBuild profile to use--switch OPAM_SWITCHUse global switch SWITCH instead of creating a local switch--upgradeUpgrade project files from drom.toml--viewOpen a browser on the sphinx documentation-yor--yesReply yes to all questions
main.exe test
Run tests
DESCRIPTION
This command performs the following actions:
1. Build the project, installing required test dependencies if needed
2. Run the test command opam exec – dune build @runtest
If the –all argument was provided, a file _drom/dune-workspace.dev is created containing a context for every existing opam switch compatible with the project min-edition field, and the tests are run on all of them. Before using this option, you should make sure that dependencies are correctly installed on all of them, using the command drom build –switch SWITCH on every SWITCH in the list. Only switches starting with a number and without the + character are selected.
USAGE
main.exe test [OPTIONS]
Where options are:
--allBuild and run tests on all compatible switches--edition VERSIONUse this OCaml edition--localCreate a local switch instead of using a global switch--profile PROFILEBuild profile to use--switch OPAM_SWITCHUse global switch SWITCH instead of creating a local switch--upgradeUpgrade project files from drom.toml-yor--yesReply yes to all questions
main.exe toml
Read TOML files and print them back on stdout
DESCRIPTION
Test the TOML parser/printer:
USAGE
main.exe toml FILE [OPTIONS]
Where options are:
FILEParse FILE and write it back on stdout
main.exe top
Run the ocaml toplevel
USAGE
main.exe top ARGUMENTS [OPTIONS]
Where options are:
ARGUMENTSProvide arguments for the ocaml toplevel--edition VERSIONUse this OCaml edition--localCreate a local switch instead of using a global switch--profile PROFILEBuild profile to use--switch OPAM_SWITCHUse global switch SWITCH instead of creating a local switch--upgradeUpgrade project files from drom.toml-yor--yesReply yes to all questions
main.exe tree
Display a tree of dependencies
DESCRIPTION
Print the project as a tree of dependencies, i.e. dependencies are printed as branches of the package they are dependencies of. If a package is itself a dependency of another package, it will be printed there.
EXAMPLE
└──drom (/src/drom)
└──drom_lib (/src/drom_lib)
└──toml 5.0.0
└──opam-file-format 2.1.1
└──ez_subst >= 0.1
└──ez_file 0.2.0
└──ez_config 0.1.0
└──ez_cmdliner 0.2.0
└──directories >= 0.2
[tools]
└── ppx_inline_test
└── ppx_expect
└── odoc
└── ocamlformat
USAGE
main.exe tree [OPTIONS]
Where options are:
main.exe uninstall
Uninstall the project from the project opam switch
USAGE
main.exe uninstall [OPTIONS]
Where options are:
--edition VERSIONUse this OCaml edition--localCreate a local switch instead of using a global switch--profile PROFILEBuild profile to use--switch OPAM_SWITCHUse global switch SWITCH instead of creating a local switch--upgradeUpgrade project files from drom.toml-yor--yesReply yes to all questions
main.exe update
Update packages in switch
DESCRIPTION
This command performs the following actions:
1. Call opam update to get information on newly available packages
2. Pin the package dependencies in the local opam switch
3. Call opam upgrade to upgrade packages in the local opam switch
4. Unpin package dependencies
USAGE
main.exe update [OPTIONS]
Where options are:
--edition VERSIONUse this OCaml edition--localCreate a local switch instead of using a global switch--profile PROFILEBuild profile to use--switch OPAM_SWITCHUse global switch SWITCH instead of creating a local switch--upgradeUpgrade project files from drom.toml-yor--yesReply yes to all questions