Skip to content

2.quick_start.md

Latest commit

 

History

History
229 lines (142 loc) · 6.43 KB

2.quick_start.md

File metadata and controls

229 lines (142 loc) · 6.43 KB

Quick Start

This documentation is NOT intended to be comprehensive; it is meant to be a quick guide for the most useful things. For more information, see the develop guide in its entirety.

Asking Questions

Before asking a question, make sure you have:

If you have any questions about KCL, you are welcome to ask your questions in KCL Github Issues. When you ask a question, please describe the details as clearly as possible so that others in the KCL community can understand, and you MUST be polite and avoid personal attack and avoid not objective comparison with other projects.

Cloning and Building KCL

System Requirements

The following hardware is recommended.

  • 10GB+ of free disk space.
  • 4GB+ RAM
  • 2+ cores

Dependencies

macOS and OS X

  • git
  • Rust 1.84+
  • Python 3.7+ (Optional, only for integration tests)

Linux

  • git
  • Rust 1.84+
  • Python3 Building Dependencies (Optional, only for integration tests)

For UNIX based systems, you can run:

yum groupinstall -y "Development Tools"
yum install -y gcc patch libffi-devel python-devel zlib-devel bzip2-devel ncurses-devel sqlite-devel 
yum install -y libpcap-devel xz-devel readline-devel tk-devel gdbm-devel db4-deve
yum -y install yum-utils
yum-builddep -y python3
yum install -y zlib* 
yum install -y openssl-devel
yum install -y glibc-static

On Debian, Ubuntu, and other apt based systems, you can run:

apt-get update

apt-get install -y git wget curl
apt-get install -y make gcc patch 
apt-get install -y python-dev libffi-dev
apt-get install -y zlib1g-dev ncurses-dev build-essential libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libreadline-dev libffi-dev

Windows

  • git
  • Rust 1.84+
  • Python 3.7+ (Only for integration tests)

Cloning

You can just do a normal git clone:

git clone https://github.com/kcl-lang/kcl.git
cd kcl

Checking

In the top level of the kcl-lang/kcl repo and run:

make check

Building

macOS, OS X and Linux

In the top level of the kcl-lang/kcl repo and run:

make build

Windows

In the top level of the kcl-lang/kcl repo and run:

.\scripts\build.ps1

Building for Different Targets

wasm32-wasip1

In the top level of the kcl-lang/kcl repo and run:

make build-wasm

Testing

Unit Testing

In the top level of the kcl-lang/kcl repo and run:

make test

See the chapters on building and testing for more details.

Grammar Integration Testing

In the top level of the kcl-lang/kcl repo and run:

make test-grammar

See the chapters on building and testing for more details. Note that the testing requires the Python environment.

Formatting

In the top level of the kcl-lang/kcl repo and run:

make fmt

Building and Testing

1. Building from Source

The project uses a Makefile to simplify build commands.

Build the CLI and Core:

make build

This will run the build script and place the binaries in the _build/dist directory.

Build specific components (e.g., LSP):

make build-lsp

2. Running Tests

Run Rust Unit Tests:

make test

Run KCL Grammar/E2E Tests (Python):

make test-grammar

Note: This requires Python 3 and the dependencies listed in Makefile (run make install-test-deps first).

3. Updating Snapshot Tests (Pattern Matching)

KCL uses insta for snapshot testing in Rust. If you make changes to the compiler (parser, evaluator, etc.) that change the output, existing tests will fail.

To update the snapshots:

  1. Install the cargo-insta tool:
cargo install cargo-insta
  1. Run the tests. If snapshots mismatch, run the review command:
cargo insta review
  1. Review the changes one by one. Press a to accept a new snapshot or r to reject it.

Contributor Procedures

Create an Issue

Every change should be accompanied by a dedicated tracking issue for that change. The main text of this issue should describe the change being made, with a focus on what users must do to fix their code. The issue should be approachable and practical; it may make sense to direct users to some other issue for the full details. The issue also serves as a place where users can comment with questions or other concerns.

When you open an issue on the kcl-lang/kcl repo, you need to to choose an issue template on this page, you can choose a template according to different situations and fill in the corresponding content, and you also need to select appropriate labels for your issue to help classify and identify.

Create a PR

When you open a PR on the kcl-lang/kcl repo, you need to assign reviewers in the KCL Dev Team list, and reviewers are the persons that will approve the PR to be tested and merged.

Please note that all code changes in the KCL project require corresponding comments and tests. For more code and test writing details, please see the chapters on code of conduct and testing.

Besides, all PRs need to have corresponding issues tracking, and need to add appropriate labels and milestone information.

Bug Fixes or "Normal" Code Changes

For most PRs, no special procedures are needed. You can just open an issue and a PR, and it will be reviewed, approved, and merged. This includes most bug fixes, refactoring, and other user-invisible changes.

Also, note that it is perfectly acceptable to open WIP PRs or GitHub Draft PRs. Some people prefer to do this so they can get feedback along the way or share their code with a collaborator. Others do this so they can utilize the CI to build and test their PR (e.g. if you are developing on a laptop).

New Features

In order to implement a new feature, usually you will need to go through the KEP process to propose a design, have discussions, etc.

After a feature is approved to be added, a tracking issue is created on the kcl-lang/kcl repo, which tracks the progress towards the implementation of the feature, any bugs reported, and eventually stabilization. The feature then can be implemented.