kcl-lib is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the `kcl-lib-bin` executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install kcl-lib

It will make the kcl-lib-bin command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall kcl-lib uninstalls.

Adding `kcl_lib` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add kcl-lib

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

kcl-lib = "0.2.125"

The kcl_lib library will be automatically available globally. Read the kcl_lib library documentation.

Back to the crate overview.

Readme

kcl-lib

Our language for defining geometry and working with our Geometry Engine efficiently. Short for KittyCAD Language, named after our Design API.

Contributing a standard library function

We've built a lot of tooling to make contributing to KCL easier. If you are interested in contributing a new standard library function to KCL, here is the rough process:

Open just the folder in your editor of choice. VS Code, for example, struggles to run rust-analyzer on the entire modeling-app directory because it's such a turducken of TS and Rust code.
Find the definition for similar standard library functions in ./kcl/src/std and place your new one near it or in the same category file.
Add your new code. A new standard library function consists of:
A pub async of the actual standard library function in Rust
A doc comment block containing at least one example using your new standard library function (the Rust compiler will error if you don't provide an example our teammates are dope)
A stdlib macro providing the name that will need to be written by KCL users to use the function (this is usually a camelCase version of your Rust implementation, which is named with snake_case)
An inner function that is published only to the crate
Add your new standard library function to the long list of CORE_FNS in mod.rs
Get a production Zoo dev token and run export ZOO_API_TOKEN=your-token-here in a terminal
Run TWENTY_TWENTY=update cargo nextest run --workspace --no-fail-fast to take snapshot tests of your example code running in the engine
Run just redo-kcl-stdlib-docs to generate new Markdown documentation for your function that will be used to generate docs on our website.
Create a PR in GitHub.

Making a Simulation Test

If you have KCL code that you want to test, simulation tests are the preferred way to do that.

Make a new sim test. Replace foo_bar with the snake case name of your test. The name needs to be unique.

just new-sim-test foo_bar

It will show the commands it ran, including the path to a new file foo_bar/input.kcl. Edit that with your KCL. If you need additional KCL files to import, include them in this directory.

Then run it.

just overwrite-sim-test foo_bar

The above should create a bunch of output files in the same directory.

Make sure you actually look at them. Specifically, if there's an execution_error.snap, it means the execution failed. Depending on the test, this may be what you expect. But if it's not, delete the snap file and run it again.

When it looks good, commit all the files, including input.kcl, generated output files in the test directory, and changes to simulation_tests.rs.

Bumping the version

If you bump the version of kcl-lib and push it to crates, be sure to update the repos we own that use it as well. These are:

Installing the kcl-lib-bin executable

Adding kcl_lib library as a dependency

Installing the `kcl-lib-bin` executable

Adding `kcl_lib` library as a dependency