Package with Dependencies
This guide shows how to create a package that depends on other aux4 packages. When your package is installed, its dependencies are automatically installed as well.
Package Structure
1my-package/
2├── .aux4 # Package metadata with dependencies
3├── LICENSE
4└── README.mdStep 1: Create the Package
Create the .aux4 file
Add the dependencies field to specify which aux4 packages your package requires:
1{
2 "scope": "myorg",
3 "name": "data-processor",
4 "version": "1.0.0",
5 "description": "Process and validate data files",
6 "license": "MIT",
7 "dependencies": [
8 "aux4/config",
9 "aux4/validator"
10 ],
11 "profiles": [
12 {
13 "name": "main",
14 "commands": [
15 {
16 "name": "process",
17 "execute": [
18 "profile:process"
19 ],
20 "help": {
21 "text": "Data processing commands"
22 }
23 }
24 ]
25 },
26 {
27 "name": "process",
28 "commands": [
29 {
30 "name": "file",
31 "execute": [
32 "aux4 config get --file ${configFile} mapping",
33 "aux4 validate json ${file}"
34 ],
35 "help": {
36 "text": "Process a data file using config and validation",
37 "variables": [
38 {
39 "name": "configFile",
40 "text": "Configuration file",
41 "default": "config.yaml"
42 },
43 {
44 "name": "file",
45 "text": "Data file to process",
46 "arg": true
47 }
48 ]
49 }
50 }
51 ]
52 }
53 ]
54}Dependency Format
Dependencies are specified as an array of strings in the format:
- scope/name — installs the latest version, and accepts any version already installed
- scope/name@version — an exact version
- scope/name@range — an npm-style semver range, resolved to the highest published version that satisfies it
1{
2 "dependencies": [
3 "aux4/config",
4 "aux4/validator@0.1.0",
5 "myorg/utils@^2.0.0",
6 "myorg/parser@~1.4.0"
7 ]
8}Version Ranges
The same range grammar works here and on the install command line (aux4 aux4 pkger install 'aux4/config@^0.2.0').
| Form | Example | Means |
|---|---|---|
| Caret | ^1.2.3 | >=1.2.3 <2.0.0 — the left-most non-zero segment is held, so ^0.2.3 is >=0.2.3 <0.3.0 and ^0.0.3 is >=0.0.3 <0.0.4 |
| Tilde | ~1.2.3 | >=1.2.3 <1.3.0; ~1.2 is >=1.2.0 <1.3.0; ~1 is >=1.0.0 <2.0.0 |
| Comparators | >=1.2.0 >1.2.0 <=2.0.0 <2.0.0 =1.2.3 !=1.2.3 | A partial version is allowed after a comparator: >=1.2 is >=1.2.0, >1.2 is >=1.3.0, <=1.2 is <1.3.0 |
| x-range | 1.x 1.2.x | 1.x is >=1.0.0 <2.0.0; 1.2.x is >=1.2.0 <1.3.0 |
| Any | * | Any published version |
| Hyphen | 1.2.3 - 2.0.0 | >=1.2.3 <=2.0.0 |
| AND | >=0.1.0 <0.2.0 | A space between terms means both must hold |
| OR | ^0.1.0 || ^0.2.0 | || separates alternatives |
Prereleases are excluded unless the range itself mentions one.
A bare version is never a range — including a partial one. 1.2.3 is exact, the prerelease 1.0.0-local is exact, latest is latest, and a bare partial such as 2.0 is exact too, unlike npm where it means 2.0.x. That is deliberate: every version already written in an existing .aux4 keeps meaning exactly what it meant before ranges existed. Write 2.0.x (or ~2.0) when you want the range.
Step 2: Create Supporting Files
LICENSE
1cat > LICENSE << 'EOF'
2MIT License
3...
4EOFTip: You can also use aux4/license to generate your LICENSE file:
1aux4 license use \
2 --name mit \
3 --owner "MyOrg" \
4 --year 2024 \
5 --project "data-processor"README.md
1cat > README.md << 'EOF'
2# Data Processor
3
4Process and validate data files.
5
6## Dependencies
7
8This package requires:
9- aux4/config
10- aux4/validator
11
12These are installed automatically when you install this package.
13
14## Usage
15
16```bash
17aux4 process file data.json --configFile settings.yaml
18```
19EOFStep 3: Build the Package
1aux4 aux4 pkger build ./out .Step 4: Install from File
1aux4 aux4 pkger install --fromFile ./out/myorg_data-processor_1.0.0.zipWhen installing, aux4 automatically:
- Resolves all dependencies
- Downloads and installs each dependency
- Installs your package
Step 5: Publish
1aux4 aux4 login
2aux4 aux4 pkger publish ./out/myorg_data-processor_1.0.0.zipStep 6: Install from aux4 Hub
1aux4 aux4 pkger install myorg/data-processorThis automatically installs:
- aux4/config
- aux4/validator
- myorg/data-processor
Transitive Dependencies
If your dependencies have their own dependencies, those are also resolved and installed automatically. aux4 handles the entire dependency tree.
For example, if aux4/config depends on aux4/aux4, the installation order would be:
- aux4/aux4
- aux4/config
- aux4/validator
- myorg/data-processor
Version Resolution
Only one version of a package is installed at a time, so when several packages depend on the same package their declarations have to agree. What each form contributes:
| Declaration | Constraint |
|---|---|
| aux4/config | Unconstrained — accepts any installed version and never blocks an upgrade |
| aux4/config@latest | Unconstrained, same as above |
| aux4/config@0.2.10 | Exact pin — a constraint of exactly 0.2.10, so it caps the whole tree: while your package is installed, nothing can move aux4/config off 0.2.10 |
| aux4/config@^0.2.0 | Range — any version it matches is acceptable |
When a newly installed package requires a version the installed dependency does not satisfy, the dependency is upgraded only with unanimous consent — to the highest published version satisfying the new requirer and every package that already depends on it. The upgrade is reported, never silent:
1Upgrading aux4/config 0.1.1 -> 0.2.10 (required by tester/upgrade-b@^0.2.0)If no published version satisfies everyone, the install fails and names the package holding it back — usually an exact pin in another package:
1tester/upgrade-b requires aux4/config@^0.2.0, but aux4/config 0.1.1 is installed.
2Cannot upgrade: tester/upgrade-a requires aux4/config@0.1.1.
3Published versions: 0.2.10, 0.2.0, 0.1.1, 0.1.0A dependency is never downgraded automatically. If the only agreeable version is older than the installed one, the install fails instead of breaking the dependent that works today.
Prefer a range (^, ~) over an exact pin in your dependencies: an exact pin caps every other package in the user's installation, and it is the most common reason an install of an unrelated package is refused. --force bypasses range enforcement entirely, leaving the dependency at the version already installed.
For the full grammar and the resolution rules, see Package Manager → Version Ranges.
List Dependencies
To see all installed packages and their dependencies:
1aux4 aux4 pkger list