# `transpile`
`transpile` is a developer CLI for migrating older Sketch V1 KCL into Sketch V2 KCL. There is one subcommand for each task
1. Convert a file to Sketch V2. Does not validate or run the resulting code may or may not run successfully
2. Run a converted file. Attempts to run the converted Sketch V2 file to see if it builds. Does not validate the output.
3. Render a converted file. Will evaluate and create an image of the result. Does not verify correctness with the corresponindg V1 code.
4. Compare a converted file's output. Will evaluage, create images for both V1 and V2 code. The comparison uses the same scaffolding as our sim tests.
The commands are stacked--issuing a run subcommand will first complete a convert, issue a render subcommand will first run convert, then run and then render.
Current status:
- `convert` is implemented
- `run` is implemented
- `render` is implemented
- `compare` is implemented
## Build
From `rust/`
```bash
cargo build -p kcl-lib --bin transpile
```
Or run it directly with Cargo:
```bash
cargo run -p kcl-lib --bin transpile -- --help
```
## Commands
```text
transpile convert <input> [OPTIONS]
transpile run <input> -o <DIR> [OPTIONS]
transpile render <input> -o <DIR> [OPTIONS]
transpile compare <input> -o <DIR> [OPTIONS]
```
There is no legacy bare `transpile <input>` mode anymore.
## Common Behavior
- `input` may be a `.kcl` file or a directory
- for non-recursive commands, a directory input resolves to `main.kcl`
- recursive mode processes every `.kcl` file under the input root
- `--ignore-file` uses `.gitignore`-like matching
- `-k, --keep-going` is only valid with `--recursive`
- `--report-file` is only valid with `--recursive`
- `-j, --json` is parsed but not implemented yet
- `-q, --quiet` suppresses CLI progress/report output, but not lower-level engine messages
## `convert`
`convert` transpiles Sketch V1 KCL to Sketch V2 KCL.
Single-file behavior:
- without `-o`, writes transpiled KCL to stdout
- with `-o`, writes the transpiled file into the output directory
- the transpiled file keeps the same filename as the input
Recursive behavior:
- requires `-r, --recursive`
- requires `-o, --out-dir`
- mirrors the input tree under `--out-dir`
- writes a grouped text report to stderr
- optionally writes the same report to `--report-file`
Example:
```bash
cargo run -p kcl-lib --bin transpile -- convert public/kcl-samples/cone
```
Example output:
```kcl
// Cone
// A cone is defined by it's diameter and height.
// Categories: Maker
@settings(defaultLengthUnit = mm, experimentalFeatures = allow)
diameter = 10
height = 10
sketch = startSketchOn(XY)
profile = sketch(on = sketch) {
line1 = line(start = [var 0mm, var 10mm], end = [var 0mm, var 0mm])
line2 = line(start = [var 0mm, var 0mm], end = [var 5mm, var 0mm])
coincident([line1.end, line2.start])
line3 = line(start = [var 5mm, var 0mm], end = [var 0mm, var 10mm])
coincident([line2.end, line3.start])
vertical(line1)
horizontal(line2)
}
region001 = region(segments = [profile.line1, profile.line2])
cone = revolve(region001, axis = Y, angle = 360.0)
```
Recursive example:
```bash
cargo run -p kcl-lib --bin transpile -- \
convert public/kcl-samples \
-r \
-k \
-o /tmp/transpile-convert \
--report-file /tmp/transpile-convert/report.txt
```
Example report:
```text
Processed: 8
Succeeded: 7
Convert failed: 1
Convert failed
- battery-module-cooling-plate/main.kcl: Execution error for `.../battery-module-cooling-plate/main.kcl`: Internal { ... }
```
## `run`
`run` transpiles to Sketch V2, persists the transpiled KCL, then executes the transpiled result.
Single-file behavior:
- requires `-o, --out-dir`
- writes the transpiled KCL into `--out-dir`
- writes `run-log.txt`
`run-log.txt` contains either:
- `success`
- or a failure marker plus the error text
Recursive behavior:
- requires `-r, --recursive`
- requires `-o, --out-dir`
- mirrors transpiled KCL under `--out-dir`
- writes one log per processed file using `<stem>-run-log.txt`
- writes grouped `Convert failed` and `Run failed` summaries
- optionally writes the same report to `--report-file`
The V2 execution path uses the same `ExecutorSettings` shape as the transpiler's execution pass.
Single-file example:
```bash
cargo run -p kcl-lib --bin transpile -- \
run public/kcl-samples/cone \
-o /tmp/transpile-run-one
```
Example output files:
```text
/tmp/transpile-run-one/main.kcl
/tmp/transpile-run-one/run-log.txt
```
Example `run-log.txt`:
```text
success
```
Recursive example:
```bash
cargo run -p kcl-lib --bin transpile -- \
run /tmp/transpile-input \
-r \
-k \
-o /tmp/transpile-run-recursive \
--report-file /tmp/transpile-run-recursive/report.txt
```
Example report:
```text
Processed: 9
Succeeded: 3
Convert failed: 0
Run failed: 6
Run failed
- cpu-cooler/fan-housing.kcl: Execution error for `/tmp/transpile-input/cpu-cooler/fan-housing.kcl`: Type { ... }
- cpu-cooler/fan.kcl: Execution error for `/tmp/transpile-input/cpu-cooler/fan.kcl`: Engine { ... }
```
Example recursive output files:
```text
/tmp/transpile-run-recursive/box/main.kcl
/tmp/transpile-run-recursive/box/main-run-log.txt
/tmp/transpile-run-recursive/cpu-cooler/fan.kcl
/tmp/transpile-run-recursive/cpu-cooler/fan-run-log.txt
```
## `render`
`render` transpiles to Sketch V2, persists the transpiled KCL, then renders a PNG from the transpiled result.
Single-file behavior:
- requires `-o, --out-dir`
- writes the transpiled KCL into `--out-dir`
- writes `rendered_model.png`
- writes `render-log.txt`
`render-log.txt` contains either:
- `success`
- or a failure marker plus the error text
Recursive behavior:
- requires `-r, --recursive`
- requires `-o, --out-dir`
- mirrors transpiled KCL under `--out-dir`
- writes one PNG per processed file using `<stem>-rendered_model.png`
- writes one log per processed file using `<stem>-render-log.txt`
- writes grouped `Convert failed` and `Render failed` summaries
- optionally writes the same report to `--report-file`
Single-file example:
```bash
cargo run -p kcl-lib --bin transpile -- \
render public/kcl-samples/cone \
-o /tmp/transpile-render-one
```
Example output files:
```text
/tmp/transpile-render-one/main.kcl
/tmp/transpile-render-one/rendered_model.png
/tmp/transpile-render-one/render-log.txt
```
Recursive example:
```bash
cargo run -p kcl-lib --bin transpile -- \
render /tmp/transpile-input \
-r \
-k \
-o /tmp/transpile-render-recursive \
--report-file /tmp/transpile-render-recursive/report.txt
```
Example recursive output files:
```text
/tmp/transpile-render-recursive/box/main.kcl
/tmp/transpile-render-recursive/box/main-rendered_model.png
/tmp/transpile-render-recursive/box/main-render-log.txt
/tmp/transpile-render-recursive/cpu-cooler/fan.kcl
/tmp/transpile-render-recursive/cpu-cooler/fan-rendered_model.png
/tmp/transpile-render-recursive/cpu-cooler/fan-render-log.txt
```
## `compare`
`compare` renders both the original Sketch V1 input and the transpiled Sketch V2 output, compares the two images, and writes a diff image.
Single-file behavior:
- requires `-o, --out-dir`
- writes the transpiled KCL into `--out-dir`
- writes `v1-rendered_model.png`
- writes `v2-rendered_model.png`
- writes `diff.png`
- writes `compare-log.txt`
`compare-log.txt` contains:
- `success` or `compare_failed`
- `similarity=<score>`
- `difference=<score>`
The compare threshold currently passes when similarity is at least `0.99`.
Recursive behavior:
- requires `-r, --recursive`
- requires `-o, --out-dir`
- mirrors transpiled KCL under `--out-dir`
- writes one V1 render per processed file using `<stem>-v1-rendered_model.png`
- writes one V2 render per processed file using `<stem>-v2-rendered_model.png`
- writes one diff image per processed file using `<stem>-diff.png`
- writes one log per processed file using `<stem>-compare-log.txt`
- writes grouped `Convert failed`, `V1 render failed`, `V2 render failed`, and `Compare failed` summaries
- optionally writes the same report to `--report-file`
Single-file example:
```bash
cargo run -p kcl-lib --bin transpile -- \
compare public/kcl-samples/cone \
-o /tmp/transpile-compare-one
```
Example output files:
```text
/tmp/transpile-compare-one/main.kcl
/tmp/transpile-compare-one/v1-rendered_model.png
/tmp/transpile-compare-one/v2-rendered_model.png
/tmp/transpile-compare-one/diff.png
/tmp/transpile-compare-one/compare-log.txt
```
Recursive example:
```bash
cargo run -p kcl-lib --bin transpile -- \
compare /tmp/transpile-input \
-r \
-k \
-o /tmp/transpile-compare-recursive \
--report-file /tmp/transpile-compare-recursive/report.txt
```
Example recursive output files:
```text
/tmp/transpile-compare-recursive/box/main.kcl
/tmp/transpile-compare-recursive/box/main-v1-rendered_model.png
/tmp/transpile-compare-recursive/box/main-v2-rendered_model.png
/tmp/transpile-compare-recursive/box/main-diff.png
/tmp/transpile-compare-recursive/box/main-compare-log.txt
```
## Ignore Files
Ignore files use `.gitignore`-like syntax.
Examples:
```text
# Ignore one file
angle-gauge/main.kcl
# Ignore a whole folder
axial-fan/
# Ignore all .kcl files except main.kcl
*.kcl
!main.kcl
```
Matching is relative to the recursive input root.
## Migration Script
The migration script at `scripts/migrate-samples-to-sketch-solve.sh` is updated to use the new cli and kept for now. It should read:
```bash
"$transpile_bin" convert "public/kcl-samples/$file" > "$out_file"
```