Skip to content

Latest commit

 

History

History
216 lines (139 loc) · 6.89 KB

2.quick_start.md

File metadata and controls

216 lines (139 loc) · 6.89 KB
Raw

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

Docker

  • docker

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

make sh-in-docker

Using a docker image is our recommended way, of course, you can also configure your local development environment according to the following content.

macOS and OS X

  • git
  • Rust 1.76+
  • LLVM 12 (Optional, only for the LLVM backend and release)
  • Python 3.7+ (Optional, only for integration tests)

You'll need LLVM installed and llvm-config in your PATH. Just download from LLVM 12 or install llvm@12 using brew.

# llvm@12 (Optional, only for the LLVM backend and release)
brew install llvm@12

Add the LLVM installation location to LLVM_SYS_120_PREFIX and the $PATH.

export LLVM_SYS_120_PREFIX=<your LLVM 12 install location>
export PATH=<your LLVM 12 install location>/bin:$PATH

Linux

  • git
  • Rust 1.76+
  • LLVM 12 (Optional, only for the LLVM backend and release)
  • 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

# clang-12 & llvm-12 (Optional, only for the LLVM backend and release), if llvm is not found, you can use ./scripts/build-llvm/build.sh to build llvm-12 locally.
yum -y install clang
clang --version
yum -y install llvm-devel
yum -y install libffi-devel
ln -s /usr/lib64/libtinfo.so.6 /usr/lib64/libtinfo.so

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

# clang-12 & llvm-12 (Optional, only for the LLVM backend and release), if llvm is not found, you can use ./scripts/build-llvm/build.sh to build llvm-12 locally.
apt-get install -y clang-12 lld-12
ln -sf /usr/bin/clang-12   /usr/bin/clang
ln -sf /usr/bin/wasm-ld-12 /usr/bin/wasm-ld

Windows

  • git
  • Rust 1.76+
  • LLVM 12 (Optional, only for the LLVM backend and release)
  • Python 3.7+ (Only for integration tests)

Please add the LLVM installation location to LLVM_SYS_120_PREFIX and the $PATH.

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:

.\build.ps1

Building for Different Targets

wasm32-wasi

In the folder kclvm 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

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.