|
| 1 | +# Build/Dist Structure with History/Archive Pattern |
| 2 | + |
| 3 | +## Philosophy |
| 4 | + |
| 5 | +**build/** (gitignored) |
| 6 | +- Workspace for building with intermediates |
| 7 | +- Archive/history of completed builds with different configs |
| 8 | +- Allows comparison, experimentation, rollback |
| 9 | +- All ephemeral but useful for development |
| 10 | + |
| 11 | +**dist/** (tracked in git) |
| 12 | +- The "blessed" canonical distribution artifact |
| 13 | +- What actually ships and gets consumed by other packages |
| 14 | +- Single source of truth for "current production build" |
| 15 | + |
| 16 | +## Recommended Structure |
| 17 | + |
| 18 | +``` |
| 19 | +packages/<package>/ |
| 20 | +├── build/ # Gitignored workspace + archive |
| 21 | +│ ├── tmp/ # Current build intermediates (cmake, obj files, etc.) |
| 22 | +│ ├── cache/ # Download caches, source clones |
| 23 | +│ └── archive/ # Historical completed builds |
| 24 | +│ ├── 2025-10-26-001-opt-size/ |
| 25 | +│ ├── 2025-10-26-002-opt-speed/ |
| 26 | +│ ├── 2025-10-26-003-debug/ |
| 27 | +│ └── latest/ # Symlink to most recent build |
| 28 | +└── dist/ # Tracked canonical releases |
| 29 | + └── <final-artifacts> |
| 30 | +``` |
| 31 | + |
| 32 | +## Package-Specific Patterns |
| 33 | + |
| 34 | +### packages/yoga-layout |
| 35 | + |
| 36 | +``` |
| 37 | +build/ |
| 38 | +├── tmp/ # cmake/, _deps/, bin/, yoga-source/ |
| 39 | +├── cache/ # Downloaded yoga source tarballs |
| 40 | +└── archive/ |
| 41 | + ├── 2025-10-26-opt-oz/ # Build with -Oz optimization |
| 42 | + │ ├── yoga.wasm |
| 43 | + │ └── yoga.js |
| 44 | + ├── 2025-10-26-opt-o3/ # Build with -O3 optimization |
| 45 | + │ ├── yoga.wasm |
| 46 | + │ └── yoga.js |
| 47 | + └── latest -> 2025-10-26-opt-oz/ |
| 48 | +
|
| 49 | +dist/ |
| 50 | +├── yoga.wasm # Blessed release (copied from build/archive/latest/) |
| 51 | +└── yoga.js |
| 52 | +``` |
| 53 | + |
| 54 | +### packages/minilm-builder |
| 55 | + |
| 56 | +``` |
| 57 | +build/ |
| 58 | +├── tmp/ # Python venv, conversion intermediates |
| 59 | +├── cache/ # Hugging Face model cache |
| 60 | +└── archive/ |
| 61 | + ├── minilm-l6-v2-int8/ # INT8 quantized |
| 62 | + │ ├── model.onnx |
| 63 | + │ └── tokenizer.json |
| 64 | + ├── minilm-l6-v2-fp16/ # FP16 quantized |
| 65 | + │ ├── model.onnx |
| 66 | + │ └── tokenizer.json |
| 67 | + └── latest -> minilm-l6-v2-int8/ |
| 68 | +
|
| 69 | +dist/ |
| 70 | +├── model.onnx # Blessed model |
| 71 | +└── tokenizer.json |
| 72 | +``` |
| 73 | + |
| 74 | +### packages/node-sea-builder |
| 75 | + |
| 76 | +``` |
| 77 | +build/ |
| 78 | +├── tmp/ # AST transformation temp files |
| 79 | +├── cache/ # Node binary cache |
| 80 | +└── archive/ |
| 81 | + ├── socket-sea-full/ # Full CLI embedded |
| 82 | + │ ├── socket-macos-arm64 |
| 83 | + │ ├── socket-linux-x64 |
| 84 | + │ └── build-manifest.json |
| 85 | + ├── socket-sea-minimal/ # Minimal CLI |
| 86 | + │ └── socket-macos-arm64 |
| 87 | + └── latest -> socket-sea-full/ |
| 88 | +
|
| 89 | +dist/ |
| 90 | +├── socket-macos-arm64 # Blessed SEA binary |
| 91 | +├── socket-linux-x64 |
| 92 | +└── socket-win-x64.exe |
| 93 | +``` |
| 94 | + |
| 95 | +### packages/node-smol-builder |
| 96 | + |
| 97 | +``` |
| 98 | +build/ |
| 99 | +├── tmp/ # Node.js build intermediates (obj files) |
| 100 | +├── cache/ # Node.js source cache |
| 101 | +└── archive/ |
| 102 | + ├── node-24.10.0-brotli-sea/ # With brotli+sea patches |
| 103 | + │ ├── node |
| 104 | + │ └── build-manifest.json |
| 105 | + ├── node-24.10.0-minimal/ # Minimal patches |
| 106 | + │ └── node |
| 107 | + ├── node-24.10.0-compressed/ # Post-compression |
| 108 | + │ └── node |
| 109 | + └── latest -> node-24.10.0-compressed/ |
| 110 | +
|
| 111 | +dist/ |
| 112 | +└── node # Blessed Node.js binary |
| 113 | +``` |
| 114 | + |
| 115 | +### packages/cli |
| 116 | + |
| 117 | +``` |
| 118 | +# Special case - dist/ is gitignored (ephemeral Rollup output) |
| 119 | +dist/ |
| 120 | +└── cli.js # Rollup bundled CLI (consumed by node-sea-builder) |
| 121 | +``` |
| 122 | + |
| 123 | +## Build Script Pattern |
| 124 | + |
| 125 | +Build scripts should support archiving with: |
| 126 | +- Timestamp-based archive naming: `YYYY-MM-DD-NNN-description` |
| 127 | +- Build manifest JSON: config, flags, version, size, date |
| 128 | +- Automatic "latest" symlink update |
| 129 | +- Optional `--archive` flag to save to archive/ |
| 130 | +- Copy from archive/latest/ → dist/ for "blessed" promotion |
| 131 | + |
| 132 | +## Benefits |
| 133 | + |
| 134 | +1. **Experimentation**: Try different optimization levels without losing previous builds |
| 135 | +2. **Comparison**: Easy A/B testing of build configurations |
| 136 | +3. **Rollback**: Keep working builds when experimenting |
| 137 | +4. **History**: Understand what changed between builds |
| 138 | +5. **Debugging**: Compare artifacts when tracking down issues |
| 139 | +6. **Documentation**: Build manifests document exact build configuration |
| 140 | + |
| 141 | +## Gitignore Strategy |
| 142 | + |
| 143 | +```gitignore |
| 144 | +# .gitignore (root) |
| 145 | +**/build/ # All build artifacts and archives (gitignored) |
| 146 | +
|
| 147 | +# dist/ NOT globally ignored - tracked in git for blessed releases |
| 148 | +# Exception: packages/cli/.gitignore ignores its own dist/ (ephemeral Rollup output) |
| 149 | +``` |
| 150 | + |
| 151 | +## Promotion Workflow |
| 152 | + |
| 153 | +1. Build → `build/tmp/` (intermediates) |
| 154 | +2. Success → `build/archive/<timestamp-config>/` (completed build) |
| 155 | +3. Update → `build/archive/latest` symlink |
| 156 | +4. Test and validate |
| 157 | +5. Promote → Copy `build/archive/latest/*` → `dist/` (blessed release) |
| 158 | +6. Commit `dist/` changes to git |
| 159 | + |
| 160 | +## Example Build Manifest |
| 161 | + |
| 162 | +`build/archive/2025-10-26-001-opt-oz/build-manifest.json`: |
| 163 | +```json |
| 164 | +{ |
| 165 | + "timestamp": "2025-10-26T14:30:00Z", |
| 166 | + "config": { |
| 167 | + "optimization": "-Oz", |
| 168 | + "target": "wasm32", |
| 169 | + "features": ["size-optimized"] |
| 170 | + }, |
| 171 | + "artifacts": [ |
| 172 | + {"file": "yoga.wasm", "size": 133120, "hash": "sha256:abc123..."}, |
| 173 | + {"file": "yoga.js", "size": 19456, "hash": "sha256:def456..."} |
| 174 | + ], |
| 175 | + "versions": { |
| 176 | + "yoga": "3.1.0", |
| 177 | + "emscripten": "3.1.50" |
| 178 | + } |
| 179 | +} |
| 180 | +``` |
0 commit comments