Merge pull request #307 from NathanReb/config-via-cli

Allow passing `x-opam-monorepo-*` solver config fields via the command line.

CHANGES.md

@@ -5,6 +5,8 @@
 - Add a `--minimal-update` flag to `lock` to generate a lockfile
   with minimum dependency changes from a previous lockfile. (#305,
   @NathanReb)
+- Add command line options to complement or overwrite `x-opam-monorepo-*`
+  fields. (#307, @NathanReb)
 
 ### Changed
 

cli/lock.ml

@@ -434,7 +434,8 @@ let preferred_versions ~minimal_update ~root target_lockfile =
       in
       name_to_version_map
 
-let extract_source_config ~opam_monorepo_cwd ~opam_files target_packages =
+let extract_source_config ~adjustment ~opam_monorepo_cwd ~opam_files
+    target_packages =
   let open Result.O in
   let target_opam_files =
     List.map (OpamPackage.Name.Set.elements target_packages) ~f:(fun name ->
@@ -444,13 +445,15 @@ let extract_source_config ~opam_monorepo_cwd ~opam_files target_packages =
     Result.List.map target_opam_files
       ~f:(Source_opam_config.get ~opam_monorepo_cwd)
   in
-  Source_opam_config.merge source_config_list
+  let* local_opam_files_config = Source_opam_config.merge source_config_list in
+  Source_opam_config.make ~opam_monorepo_cwd ~adjustment
+    ~local_opam_files_config
 
 let run (`Root root) (`Recurse_opam recurse) (`Build_only build_only)
     (`Allow_jbuilder allow_jbuilder) (`Ocaml_version ocaml_version)
     (`Require_cross_compile require_cross_compile)
-    (`Minimal_update minimal_update) (`Target_packages specified_packages)
-    (`Lockfile explicit_lockfile) () =
+    (`Minimal_update minimal_update) (`Config_adjustment adjustment)
+    (`Target_packages specified_packages) (`Lockfile explicit_lockfile) () =
   let open Result.O in
   let* local_packages = local_packages ~versions:specified_packages root in
   let* target_packages =
@@ -461,7 +464,8 @@ let run (`Root root) (`Recurse_opam recurse) (`Build_only build_only)
   let* opam_files = local_paths_to_opam_map local_packages in
   let* lockfile_path = lockfile_path ~explicit_lockfile ~target_packages root in
   let* source_config =
-    extract_source_config ~opam_monorepo_cwd:root ~opam_files target_packages
+    extract_source_config ~adjustment ~opam_monorepo_cwd:root ~opam_files
+      target_packages
   in
   let* opam_provided =
     opam_provided_packages ~opam_monorepo_cwd:root opam_files target_packages
@@ -497,6 +501,11 @@ let run (`Root root) (`Recurse_opam recurse) (`Build_only build_only)
 
 open Cmdliner
 
+let config_adjustment =
+  Common.Arg.named
+    (fun x -> `Config_adjustment x)
+    Source_opam_config.cli_adjustment
+
 let recurse_opam =
   let doc =
     "Recursively look for opam files to include as local packages in \
@@ -602,7 +611,8 @@ let term =
   Common.Term.result_to_exit
     Cmdliner.Term.(
       const run $ Common.Arg.root $ recurse_opam $ build_only $ allow_jbuilder
-      $ ocaml_version $ require_cross_compile $ minimal_update $ packages
-      $ Common.Arg.lockfile $ Common.Arg.setup_logs ())
+      $ ocaml_version $ require_cross_compile $ minimal_update
+      $ config_adjustment $ packages $ Common.Arg.lockfile
+      $ Common.Arg.setup_logs ())
 
 let cmd = Cmd.v info term

doc/lock.mld

@@ -24,3 +24,175 @@ versions from the previous lock file if possible.
 This mode is of course only useful if you run it after changing your
 dependency specification in one of your opam files as it will otherwise simply
 produce the same lock file.
+
+{2 Configuring [lock]'s solver}
+
+To generate a lock file, [opam-monorepo] first needs to find a solution
+that satisfies the project's dependencies and runs an opam solver based
+on [0install] for that.
+
+There are certain aspects that can be configured either via the command line
+or in your opam files directly.
+
+{3 Opam Repositories}
+
+You can configure which repositories the solver will use to get the list
+of existing packages and their associated metadata.
+
+By default it will use the repositories set in your current switch.
+
+You can explicitly set the repositories to use, making [opam-monorepo] ignore
+the ones configured in the switch, along with in pins.
+You can do so by setting the [x-opam-monorepo-opam-repositories] extension
+in any of your local opam files. For instance:
+
+{[
+x-opam-monorepo-opam-repositories: [
+  "git+https://github.com/ocaml/opam-repositories"
+  "git+https://github.com/dune-universe/opam-overlays"
+]
+]}
+
+Alternatively you can set it via the command line by running:
+
+{[
+opam monorepo lock --opam-repositories \
+  '[git+https://github.com/ocaml/opam-repositories,git+https://github.com/dune-universe/opam-overlays]'
+]}
+
+The [--opam-repositories] option will overwrite any locally defined
+[x-opam-monorepo-opam-repositories] field. If you simply want to add extra
+repositories you can use [--add-opam-repositories] instead:
+
+{[
+opam monorepo lock --add-opam-repositories '[git+https://me.com/my-repo]'
+]}
+
+When the field is set in multiple opam files and eventually through the
+[--add-opam-repositories] option, they are combined into a set, removing any
+duplicates. That set of URLs is what the solver will then use to get the
+available packages metadata in place of the ones set in the switch.
+
+You can use any URL supported by opam, that includes local or remote git and
+tarball URLs as well as local folders.
+
+{b IMPORTANT NOTE}: this feature is still in development and only local
+folders URLs are supported at the moment. Support for remote URLs will be
+available shortly! In the meantime you can set any repository in your
+switch, local or remote. As long as you don't set any repository explicitly
+via [opam-monorepo]'s options or opam extension, it will be able to use
+anything setup in the switch. 
+
+File system URLs cannot use relative paths. If you wish to use local folders for
+your repos, you can use the [$OPAM_MONOREPO_CWD] variable that will be replaced
+at runtime by [opam-monorepo]'s current working directory or the folder passed
+to [--root]. This will allow you to refer to repos defined within your workspace
+without writing path specific to your machine.
+
+For instance if you have a repository defined in a [data/repo] sub folder of
+your project, you can get the solver to use it by setting:
+
+{[
+x-opam-monorepo-opam-repositories: [
+  "file://$OPAM_MONOREPO_CWD/data/repo"
+]
+]}
+
+{3 Opam Global Variables}
+
+You can set the value of opam global variables such as [arch] or
+[os-distribution]. These can have an impact on the solution picked by the
+solver as some package availability or dependencies vary based on their value.
+
+By default [opam-monorepo] will use the variables set in your current switch.
+
+You can explicitly set the variables defined along with their value, making
+[opam-monorepo] ignore any variable defined in the switch.
+You can do so by setting the [x-opam-monorepo-opam-global-vars] opam extension.
+For instance:
+
+{[
+x-opam-monorepo-opam-global-vars: [
+  [ "arch" "x86_64" ]
+  [ "os-distribution" "debian" ]
+  [ "os-family" "debian" ]
+  [ "os-version" "testing" ]
+]
+]}
+
+Alternatively you can set it via the command line by running:
+
+{[
+opam monorepo lock \
+  --opam-global-vars [[arch,x86_64],[os-distribution,debian],[os-family,debian],[os-version,testing]]
+]}
+
+The [--opam-global-vars] option will overwrite any locally defined
+[x-opam-monorepo-opam-global-vars] field. If you simply want to define extra
+variables you can use [--add-opam-global-vars] instead:
+
+{[
+opam monorepo lock --add-global-vars [[some_var,some_value]]
+]}
+
+When the field is set in multiple opam files and eventually through the
+[--add-opam-global-vars] option, they are combined. A variable can appear
+multiple times as long as it is assigned the same value, it will error out
+otherwise.
+
+The variables can be assigned boolean, string or list of strings values.
+The syntax for the opam field is the following:
+
+{[
+x-opam-monorepo-global-vars: [
+  ["boolean_var" true]
+  ["string_var" "abc"]
+  ["string_list_var" ["abc" "def"]]
+]
+]}
+
+The syntax for command line argument is the following:
+
+{[
+--opam-global-vars [[boolean_var,true],[string_var,abc],[string_list_var,[abc,def]]]
+]}
+
+{3 Opam provided packages}
+
+This feature has its own {{!page-"opam-provided"}documentation page}.
+
+You can define a set of packages that should be installed via opam rather
+than incorporated into the duniverse. This will influence how the solver
+treats those packages (they do not have to build with dune for instance).
+
+By default all dependencies outside of [dune], [ocaml] and a few other base
+packages are treated as if they were to be incorporated in the duniverse.
+
+You can define which packages should be installed via opam by setting the
+[x-opam-monorepo-opam-provided] field in any of your local opam files. For
+instance:
+
+{[
+x-opam-monorepo-opam-provided: [
+  "tezos-rust-libs"
+  "ocamlfind"
+]
+]}
+
+Alternatively you can set it via the command line by running:
+
+{[
+opam monorepo lock --opam-provided [tezos-rust-libs,ocamlfind]
+]}
+
+The [--opam-provided] option will overwrite any locally defined
+[x-opam-monorepo-opam-provided] field. If you simply want to define extra
+opam provided packages you can use [--add-opam-provided] instead:
+
+{[
+opam monorepo lock --add-opam-provided [some-other-package]
+]}
+
+When the field is set in multiple opam files and eventually through the
+[--add-opam-provided] option, they are combinded into a set, removing
+duplicates.

lib/dune

@@ -1,4 +1,4 @@
 (library
  (name duniverse_lib)
- (libraries base bos fmt logs ocaml-version opam-0install opam-file-format
-   opam-format sexplib stdext threads uri))
+ (libraries base bos cmdliner fmt logs ocaml-version opam-0install
+   opam-file-format opam-format sexplib stdext threads uri))