coswitch

$ bazel run @coswitch//new

bazel_dep(name = "alcotest",        version = "0.0.0")

You can run @coswitch from any directory equipped with the following files: .bazelrc, MODULE.bazel, and WORKSPACE.bazel. If you install it locally, as described below, you can run it independent of Bazel.

1. The common prefix on these lines directs Bazel to use these directives for all commands (build, test, run, query).

2. Imported file must contain --registry=…​ for your coswitch; see below

3. @coswitch is not yet available in the Bazel Central Repository (BRC)

4. URL for the BCR. Bazel automatically uses it if no --registry directive is used; otherwise it must be explicitly required, as here.

5. Optional. Will be ignored if .config/user.bazelrc does not exist. Do not put this file under version control. This allows each user to customize builds by adding Bazel directives. Any file name can be used; .config/user.bazelrc is just an OBazl convention.

1. Path created by coswitch; for example, /home/<uid>/.opam/5.1.1/share/obazl

1. A common convention is to use the same name for the module and the basename of the root directory, but this is not a requirement.

2. The least Bazel version that supports Bazel modules (?)

3. See the Releases page for the latest version identifier.

1. With bzlmod enabled this file will be ignored but it must exist. This constraint will be removed in a future version of Bazel.

1. INFO messages are printed by Bazel

2. By default coswitch is created for current switch; override with -s or --switch

3. Printed by @coswitch//new (with $HOME expanded)

By default each coswitch is installed in the corresponding switch, in $OPAM_SWITCH_PREFIX/share/obazl. To instead install to $XDG_DATA_HOME/obazl, pass ` — -x` or ` — --xdg`.

You can ask @coswitch//new to print more information by passing -v one or more times; such arguments must be passed after --; for example:

To silence messages from @coswitch//new, pass -q or --quiet.

To silence messages from Bazel you can use these directives (documented at Commands and Options and Command-Line Reference), which may be passed on the command line (NB: before --) or added to .config/user.bazelrc:

1. where <event> is one of: fatal, error, warning, info, progress, debug, start, finish, subcommand, stdout, stderr, pass, fail, timeout, cancelled or depchecker

Once you have configured a coswitch, you must tell Bazel to use it by passing a --registry= directive pointing to the coswitch. For example,

You can pass this on the command line, but it will be more convenient to put it in a bazelrc file. One strategy is to put it in .config/coswitch_registry.bazelrc, and then add this to .bazelrc (as noted above):

If you work with multiple OPAM switches, you will need to create a coswitch for each; then to change to use a different coswitch, edit your --registry directive.

For better integration with OPAM and the shell, you can use a shell script to wrap the bazel invocation. When you install coswitch, a sample script is installed at $XDG_DATA_HOME/obazl/templates/bazel_wrapper.sh. Copy this file to tools/bazel (it must be an executable named bazel). Now when you run a bazel command, control will be passed to this script, which runs opam switch show to discover the current switch, and then constructs the appropriate --registry directive and adds it to the bazel command.

Once @coswitch//new has done its work, the packages in the switch are available to Bazel build programs as standard Bazel labels. The labels are constructed according to a simple schema: package p becomes @p//lib/p; package p.q.r becomes @p//lib/q/r. Executables are labelled @p//bin/p; they are also accesible as @ocaml//bin:p.

Some examples:

This will install an optimized build of the coswitch executable to $HOME/.local/bin/coswitch; it will also install some template files to $XDG_DATA_HOME/obazl/templates.

You can install the executable to a different directory by passing ` — -b /path/to/bindir`.

Once you have installed coswitch on your local system you can remove its bazel_dep from your MODULE.bazel file, and run $ coswitch.

Misconfigured repositories may result in a message like the following:

$XDG_DATA_HOME/obazl/opam/<switch name>
$XDG_DATA_HOME/obazl/registry/<switch name>

A coswitch is essentially a mirror of a switch. Symlinks are used to integrate the the two.

For example, the coswitch record for package yojson of switch fiveone (as describe below in Creating an OPAM switch) looks like this:

If installed with ` — --xdg`:

For each Bazel module in the coswitch (i.e. package in the switch), @coswitch//new also creates a Bazel registry record. The Bazel registry has this structure (documented at Bazel registries):

1. Contains coswitch package entries as described above

2. Contains bzlmod registry records

With ` — --xdg`:

The bazel_registry.json file contains the path to pkg entries in the OPAM switch:

1. Not used

2. Relative to cwd; serves as based dir for relative paths in registry records

For XDG installations:

1. Not used

2. Registry records implicitly reference this base path (in this case, absolute path)

The modules subdirectory contains one record per Bazel module. The record for yojson:

1. Coswitch entries always use version 0.0.0, which resolves to whatever version is installed in the OPAM switch. This obviates the need to keep bazel_dep entries in MODULE.bazel files in sync with the OPAM switch.

The source.json file contains the information Bazel needs to find the "source" (i.e. OPAM package) for the Bazel module. In a networked registry, this would be a URL and integrity checksum. But this registry is for local use only, so instead the source.json file looks like this:

1. Tells Bazel to use the module_base_path field of the registry’s bazel_registry.json file to construct the local path to module source.

2. To be interpreted as the desired subdirectory of module_base_path.

Together, bazel_registry.json and yojson/0.0.0/source.json indicate that the sources for yojson are located at $HOME/.local/share/obazl/opam/fiveone/lib/yojson.

See section above on --registry directives.

$ opam switch create my511 5.1.1

$ opam switch

opam install base bigarray-compat cppo csexp

$ opam list