anil.recoil.org
forked from
mtelvers.tunbury.org/repo-tool
A CLI tool that generates an opam repository and monorepo from a list of git repos
1# monopam
2
3A CLI tool that generates an opam repository and monorepo from a list of git repositories.
4
5## Overview
6
7`monopam` reads a text file containing git repository URLs and:
8
91. Clones each repository into a `vendor/` directory
102. Generates an opam repository structure in `opam-repository/`
113. Creates a `setup.sh` script to pin packages and install dependencies
124. Sets up dune to build everything as a monorepo
13
14This is useful for creating a local development environment with multiple interdependent packages that may not yet be published to opam.
15
16## Installation
17
18```bash
19opam install . --deps-only
20dune build
21dune install
22```
23
24Or run directly:
25
26```bash
27dune exec monopam -- <args>
28```
29
30## Usage
31
32```bash
33monopam INPUT_FILE [-o OUTPUT_DIR] [-v]
34```
35
36### Arguments
37
38- `INPUT_FILE` - Path to a text file containing git repository URLs (one per line)
39- `-o, --output DIR` - Output directory (default: `opam-repository`)
40- `-v, --verbose` - Enable verbose output
41
42### Input File Format
43
44```
45# Comments start with #
46https://github.com/user/repo1.git
47https://github.com/user/repo2.git main
48https://tangled.org/user/repo3
49```
50
51Each line contains a git URL, optionally followed by a branch name.
52
53## Output Structure
54
55```
56output-dir/
57├── dune-project # Dune project file
58├── dune # Top-level dune config
59├── setup.sh # Setup script for opam switch
60├── opam-repository/
61│ ├── repo # opam repository metadata
62│ └── packages/
63│ └── <pkg>/
64│ └── <pkg>.dev/
65│ └── opam # Package opam file with url stanza
66└── vendor/
67 ├── dune # Lists vendor subdirectories
68 ├── repo1/ # Cloned source code
69 ├── repo2/
70 └── ...
71```
72
73## Setting Up the Monorepo
74
75After running `monopam`, set up the development environment:
76
77```bash
78cd output-dir
79./setup.sh
80```
81
82The setup script will:
831. Create a local opam switch with OCaml 5.4.0
842. Pin all vendor packages
853. Install dependencies (including test dependencies)
864. Run `dune build`
87
88Alternatively, run the steps manually:
89
90```bash
91cd output-dir
92opam switch create . 5.4.0 -y
93opam pin add -ny <pkg1> vendor/<repo1>
94opam pin add -ny <pkg2> vendor/<repo2>
95# ... for each package
96opam install -y --deps-only --with-test <pkg1> <pkg2> ...
97opam exec -- dune build --root .
98```
99
100## Using the opam Repository as an Overlay
101
102You can also use just the generated opam repository as an overlay:
103
104```bash
105opam repository add local /path/to/output-dir/opam-repository
106opam update
107opam install <package-name>
108```
109
110## Incremental Updates
111
112Running `monopam` again on an existing output directory will:
113- Update existing repositories with `git pull`
114- Clone any new repositories
115- Regenerate the opam repository and setup script
116
117## Example
118
119```bash
120# Create a repos.txt file
121cat > repos.txt << EOF
122https://github.com/user/ocaml-foo
123https://github.com/user/ocaml-bar
124https://tangled.org/user/ocaml-baz
125EOF
126
127# Generate the monorepo
128monopam repos.txt -o my-monorepo -v
129
130# Set up and build
131cd my-monorepo
132./setup.sh
133```