Skip to content

Commit c2135c6

Browse files
jensensjensens
committed
better examples
1 parent 77a2c66 commit c2135c6

File tree

4 files changed

+226
-5
lines changed

4 files changed

+226
-5
lines changed

‎example/README.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# mxdev Example Configuration
2+
3+
This directory contains example configuration files that demonstrate various mxdev features.
4+
5+
## Files
6+
7+
- **example.ini** - Main mxdev configuration file demonstrating various features
8+
- **requirements-infile.txt** - Example input requirements file
9+
- **constraints-infile.txt** - Example input constraints file
10+
11+
## Running the Example
12+
13+
To use this example configuration:
14+
15+
```bash
16+
# From the example directory
17+
cd example
18+
19+
# Run mxdev with the example configuration
20+
mxdev -c example.ini
21+
22+
# This will:
23+
# 1. Read requirements-infile.txt and constraints-infile.txt
24+
# 2. Fetch source repositories defined in example.ini
25+
# 3. Generate requirements-outfile.txt and constraints-outfile.txt
26+
#
27+
# Note: The example uses placeholder repositories that don't exist.
28+
# Replace them with real repositories to actually run it.
29+
```
30+
31+
## Features Demonstrated
32+
33+
### Settings Section
34+
35+
The `[settings]` section demonstrates:
36+
37+
- **Input/Output files**: Custom names for requirements and constraints
38+
- **main-package**: Defining the main package being developed
39+
- **version-overrides**: Overriding specific package versions from upstream constraints
40+
- **ignores**: Excluding packages from constraints (e.g., your main package)
41+
- **default-target**: Custom directory for checked out sources
42+
- **threads**: Parallel fetching for faster checkouts
43+
- **Variable substitution**: Reusable variables like `${settings:github}`
44+
45+
### Package Sections
46+
47+
Different package configurations showcase:
48+
49+
1. **foo.bar** - Basic package with branch and extras
50+
2. **plone.behavior** - Shallow clone with `depth=1` (useful for CI)
51+
3. **package.with.submodules** - Git submodules with `submodules=recursive`
52+
4. **package.not.in.root** - Package in subdirectory using `subdirectory`
53+
5. **package.skip.install** - Clone only, skip pip install with `install-mode=skip`
54+
6. **package.custom.location** - Custom target directory with `target`
55+
56+
## Git-Specific Features
57+
58+
### Shallow Clones (depth)
59+
60+
```ini
61+
[plone.behavior]
62+
url = ${settings:github}plone/plone.behavior.git
63+
depth = 1 # Only fetch latest commit
64+
```
65+
66+
Or set globally via environment variable:
67+
```bash
68+
export GIT_CLONE_DEPTH=1
69+
```
70+
71+
### Submodules
72+
73+
```ini
74+
[package.with.submodules]
75+
url = ${settings:github}orga/package.with.submodules.git
76+
submodules = recursive # Options: always (default), checkout, recursive
77+
```
78+
79+
### Subdirectories
80+
81+
For monorepos where the Python package is not in the repository root:
82+
83+
```ini
84+
[package.not.in.root]
85+
url = ${settings:github}orga/monorepo.git
86+
subdirectory = packages/mypackage
87+
```
88+
89+
## Installation Modes
90+
91+
### Skip Installation
92+
93+
Just clone the repository, don't install with pip (useful for configuration repositories):
94+
95+
```ini
96+
[package.skip.install]
97+
url = ${settings:github}orga/config-only.git
98+
install-mode = skip
99+
```
100+
101+
### Direct Installation (default)
102+
103+
Install package with `pip install -e PACKAGEPATH`:
104+
105+
```ini
106+
[foo.bar]
107+
url = ${settings:github}orga/foo.bar.git
108+
# install-mode = direct # This is the default
109+
```
110+
111+
## Version Overrides
112+
113+
Override versions from upstream constraints files:
114+
115+
```ini
116+
[settings]
117+
version-overrides =
118+
baz.baaz==1.9.32
119+
somepackage==3.0.0
120+
```
121+
122+
**Note**: If using [uv](https://pypi.org/project/uv/), use its native override support instead:
123+
124+
```bash
125+
# Create overrides.txt with version overrides
126+
uv pip install --override overrides.txt -r requirements-mxdev.txt
127+
```
128+
129+
## Ignoring Packages
130+
131+
Exclude packages from constraints (useful for your main package):
132+
133+
```ini
134+
[settings]
135+
ignores =
136+
my.mainpackage
137+
package.to.ignore
138+
```
139+
140+
## Custom Variables
141+
142+
Define reusable variables in the settings section:
143+
144+
```ini
145+
[settings]
146+
github = git+ssh://git@github.com/
147+
gitlab = git+ssh://git@gitlab.com/
148+
149+
[foo]
150+
url = ${settings:github}orga/foo.git
151+
152+
[bar]
153+
url = ${settings:gitlab}company/bar.git
154+
```
155+
156+
## Real-World Examples
157+
158+
For real production examples, see:
159+
160+
- [plone.org backend](https://github.com/plone/plone.org/tree/main/backend)
161+
- [Conestack](https://github.com/conestack/conestack/)
162+
163+
## Additional Resources
164+
165+
See the main [README.md](../README.md) for complete documentation of all configuration options.

‎example/constraints-infile.txt‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,6 @@
1-
-c https://dist.plone.org/release/6.0.0a1/constraints.txt
2-
bar==1.2.3
1+
# Example: Use stable constraints from an upstream source
2+
-c https://dist.plone.org/release/6.1-latest/constraints.txt
3+
4+
# Additional package constraints
5+
bar==1.2.3
6+
baz==2.0.0

‎example/example.ini‎

Lines changed: 48 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,30 @@
11
[settings]
2+
# Input/Output configuration
23
requirements-in = requirements-infile.txt
34
constraints-out = constraints-outfile.txt
45
requirements-out = requirements-outfile.txt
56

6-
; github = git+https://github.com/
7+
# Main package being developed (optional)
8+
# If defined in constraints, add to ignores below
9+
main-package = -e .[test]
10+
11+
# Override versions from upstream constraints
12+
version-overrides =
13+
baz.baaz==1.9.32
14+
15+
# Ignore packages from constraints (e.g., main package)
16+
ignores =
17+
my.mainpackage
18+
19+
# Custom target directory for sources
20+
default-target = ./sources
21+
22+
# Number of parallel threads for fetching
23+
threads = 8
24+
25+
# Custom variables for reuse
726
github = git+ssh://git@github.com/
27+
; Alternative: github = git+https://github.com/
828

929
[foo.bar]
1030
url = ${settings:github}orga/foo.bar.git
@@ -13,4 +33,30 @@ extras = test,baz
1333

1434
[plone.behavior]
1535
url = ${settings:github}plone/plone.behavior.git
16-
branch = master
36+
branch = main
37+
# Use shallow clone for faster checkout (useful in CI)
38+
depth = 1
39+
40+
[package.with.submodules]
41+
url = ${settings:github}orga/package.with.submodules.git
42+
branch = main
43+
# Control submodule behavior: always (default), checkout, recursive
44+
submodules = recursive
45+
46+
[package.not.in.root]
47+
url = ${settings:github}orga/monorepo.git
48+
branch = main
49+
# Package is in a subdirectory of the repository
50+
subdirectory = packages/mypackage
51+
52+
[package.skip.install]
53+
url = ${settings:github}orga/config-only.git
54+
branch = main
55+
# Just clone, don't install with pip
56+
install-mode = skip
57+
58+
[package.custom.location]
59+
url = ${settings:github}orga/special.git
60+
branch = develop
61+
# Override default target directory for this package
62+
target = ./vendor/special

‎example/requirements-infile.txt‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,8 @@
1-
foo==11.2
1+
# Main requirements file
2+
# Reference constraints for version pinning
23
-c constraints-infile.txt
4+
5+
# Core packages
6+
foo==11.2
7+
setuptools
8+
wheel

0 commit comments

Comments
 (0)