Skip to content

Commit

Permalink
Merge pull request #161 from Peefy/add-more-installation-notes
Browse files Browse the repository at this point in the history
feat: add more install trouble shooting messages on windows platforms
  • Loading branch information
Peefy authored Sep 19, 2023
2 parents e7b33e0 + 4a370b5 commit 3fa168f
Show file tree
Hide file tree
Showing 12 changed files with 252 additions and 6 deletions.
2 changes: 2 additions & 0 deletions docs/user_docs/getting-started/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,8 @@ GitCommit: {git commit}

For all the above operating systems and installation methods, if you want to use [KCL Python Plugin](/docs/reference/plugin/overview), you need to ensure that Python 3.7+ is installed and add the python3 command to your PATH environment variable.

If you are unable to successfully install and run KCL, you can refer to [here](/docs/user_docs/support/faq-install)

## 2. Install KCL IDE Extension

### VS Code
Expand Down
6 changes: 5 additions & 1 deletion docs/user_docs/support/faq-install.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,4 +26,8 @@ Please ensure that the following dependencies are in your PATH:

+ `clang` for MacOS
+ `gcc` for Linux
+ `cl.exe` for Windows, which can be obtained by installing MSVC
+ `cl.exe` for Windows, which can be obtained by installing `MSVC`

## Encountering exit status 0xc0000135 error on Windows platform

Please ensure that .NET Framework and MSVC are installed on your Windows. If not installed, you can install them and try again.
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,8 @@ GitCommit: {git commit}

对于上述所有安装方式, 如果您想使用 [KCL Python 插件](/docs/reference/plugin/overview), 需要确保您已经安装了 Python 3.7+ 并将 python3 命令添加到您的 PATH 中。

如果您无法成功安装并运行 KCL,可以参考[这里](/docs/user_docs/support/faq-install)

## 2. 安装 KCL IDE 插件

### VS Code
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,14 @@ xattr -rd com.apple.quarantine /path/to/kcl

其中,/path/to/kcl 是 kcl 应用程序的完整路径。运行命令后,应用程序将被添加到白名单中,Gatekeeper 将不再阻止其运行。

## 在 Windows/Linux/MacOS 平台上抱 program not found 或者 run linker failed 错误
## 在 Windows/Linux/MacOS 平台上报 program not found 或者 run linker failed 错误

请确保如下依赖在您的 PATH 中

+ MacOS: `clang`
+ Linux: `gcc`
+ Windows: `cl.exe` (可以通过安装 MSVC 获得)
+ Windows: `cl.exe` (可以通过安装 `MSVC` 获得)

## 在 Windows 平台上遇到 exit status 0xc0000135 错误

请确保您的 Windows 上安装了 .NET Framework 和 MSVC,如没有安装,可以安装并重试
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,8 @@ GitCommit: {git commit}

对于上述所有安装方式, 如果您想使用 [KCL Python 插件](/docs/reference/plugin/overview), 需要确保您已经安装了 Python 3.7+ 并将 python3 命令添加到您的 PATH 中。

如果您无法成功安装并运行 KCL,可以参考[这里](/docs/user_docs/support/faq-install)

## 2. 安装 KCL IDE 插件

### VS Code
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,14 @@ xattr -rd com.apple.quarantine /path/to/kcl

其中,/path/to/kcl 是 kcl 应用程序的完整路径。运行命令后,应用程序将被添加到白名单中,Gatekeeper 将不再阻止其运行。

## 在 Windows/Linux/MacOS 平台上抱 program not found 或者 run linker failed 错误
## 在 Windows/Linux/MacOS 平台上报 program not found 或者 run linker failed 错误

请确保如下依赖在您的 PATH 中

+ MacOS: `clang`
+ Linux: `gcc`
+ Windows: `cl.exe` (可以通过安装 MSVC 获得)
+ Windows: `cl.exe` (可以通过安装 `MSVC` 获得)

## 在 Windows 平台上遇到 exit status 0xc0000135 错误

请确保您的 Windows 上安装了 .NET Framework 和 MSVC,如没有安装,可以安装并重试
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,8 @@ GitCommit: {git commit}

For all the above operating systems and installation methods, if you want to use [KCL Python Plugin](/docs/reference/plugin/overview), you need to ensure that Python 3.7+ is installed and add the python3 command to your PATH environment variable.

If you are unable to successfully install and run KCL, you can refer to [here](/docs/user_docs/support/faq-install)

## 2. Install KCL IDE Extension

### VS Code
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# Share Your Package to ghcr.io

[kpm](https://github.com/kcl-lang/kpm) is a tool for managing kcl packages. This article will guide you on how to use kpm to push your kcl package to an OCI Registry for publication. kpm uses [ghcr.io](https://ghcr.io) as the default OCI Registry, and you can change the default OCI Registry by modifying the kpm configuration file. For information on how to modify the kpm configuration file, see [kpm oci registry](https://github.com/kcl-lang/kpm/blob/main/docs/kpm_oci.md#kpm-registry)

Here is a simple step-by-step guide on how to use kpm to push your kcl package to ghcr.io.

## Step 1: Install kpm

First, you need to install kpm on your computer. You can follow the instructions in the [kpm installation documentation](https://kcl-lang.io/docs/user_docs/guides/package-management/installation).

## Step 2: Create a ghcr.io token

If you are using the default OCI Registry of kpm, to push a kcl package to ghcr.io, you need to create a token for authentication. You can follow the instruction.

- [Creating a ghcr.io access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)

## Step 3: Log in to ghcr.io

After installing kpm and creating a ghcr.io token, you need to log in to ghcr.io using kpm. You can do this using the following command:

```shell
kpm login ghcr.io -u <USERNAME> -p <TOKEN>
```

Where `<USERNAME>` is your GitHub username, `<TOKEN>` is the token you created in step 2

For more information on how to log in to ghcr.io using kpm, see [kpm login](https://kcl-lang.io/docs/reference/package-management/command-reference/login).

## Step 4: Push your kcl package

Now, you can use kpm to push your kcl package to ghcr.io.

### 1. A valid kcl package

First, you need to make sure that what you are pushing conforms to the specifications of a kcl package, i.e., it must contain valid kcl.mod and kcl.mod.lock files.

If you don't know how to get a valid kcl.mod and kcl.mod.lock, you can use the `kpm init` command.

```shell
# Create a new kcl package named my_package
kpm init my_package
```

The `kpm init my_package` command will create a new kcl package `my_package` for you and create the `kcl.mod` and `kcl.mod.lock` files for this package.

If you already have a directory containing kcl files `exist_kcl_package`, you can use the following command to convert it into a kcl package and create valid `kcl.mod` and `kcl.mod.lock` files for it.

```shell
# In the exist_kcl_package directory
$ pwd
/home/user/exist_kcl_package

# Run the `kpm init` command to create the `kcl.mod` and `kcl.mod.lock` files
$ kpm init
```

For more information on how to use `kpm init`, see [kpm init](https://kcl-lang.io/docs/reference/package-management/command-reference/init).

### 2. Pushing the KCL Package

You can use the following command in the root directory of your `kcl` package:

```shell
# In the root directory of the exist_kcl_package package
$ pwd
/home/user/exist_kcl_package

# Pushing the KCL Package to Default OCI Registry
$ kpm push
```

After completing these steps, you have successfully pushed your KCL Package to the default OCI Registry.
For more information on how to use `kpm push`, see [kpm push](https://kcl-lang.io/docs/reference/package-management/command-reference/push).
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# Share Your Package to docker.io

[kpm](https://github.com/KusionStack/kpm) is a tool for managing kcl packages. This article will show you how to use kpm to push your kcl packages to docker.io.

Here is a simple step-by-step guide on how to use kpm to push your kcl package to docker.io.

## Step 1: Install kpm

First, you need to install kpm on your computer. You can follow the instructions in the [kpm installation documentation](https://kcl-lang.io/docs/user_docs/guides/package-management/installation).

## Step 2: Create a docker.io account

If you want to use `docker.io` as the OCI registry to share your kcl package with others, you need to create a `docker.io` account to support the push of your kcl package.

## Step 3: Log in to docker.io

You can use the following command to log in to docker.io.

```shell
kpm login -u <USERNAME> -p <PASSWORD> docker.io
```

Where `<USERNAME>` is your `docker.io` username, and `<PASSWORD>` is your `docker.io` password.

For more information on how to log in to docker.io using kpm, see [kpm login](https://kcl-lang.io/docs/reference/package-management/command-reference/login).

## Step 4: Push your kcl package

Now, you can use kpm to push your kcl package to `docker.io`.

### 1. A valid kcl package

First, you need to make sure that what you are pushing conforms to the specifications of a kcl package, i.e., it must contain valid kcl.mod and kcl.mod.lock files.

If you don't know how to get a valid kcl.mod and kcl.mod.lock, you can use the `kpm init` command.

Create a new kcl package named `my_package`.
```shell
kpm init my_package
```

The `kpm init my_package` command will create a new kcl package `my_package` for you and create the `kcl.mod` and `kcl.mod.lock` files for this package.

If you already have a directory containing kcl files `exist_kcl_package`, you can use the following command to convert it into a kcl package and create valid `kcl.mod` and `kcl.mod.lock` files for it.

Run the `kpm init` command under the `exist_kcl_package` directory.
```shell
kpm init
```

For more information on how to use `kpm init`, see [kpm init](https://kcl-lang.io/docs/reference/package-management/command-reference/init).

### 2. Pushing the KCL Package

You can use the following command in the root directory of your `kcl` package:

Run the `kpm push` command under the `exist_kcl_package` directory.
```shell
kpm push oci://docker.io/<USERNAME>/exist_kcl_package
```

After completing these steps, you have successfully pushed your KCL Package `exist_kcl_package` to `docker.io`.
For more information on how to use `kpm push`, see [kpm push](https://kcl-lang.io/docs/reference/package-management/command-reference/push).
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Push Your KCL Package by GitHub Action

[kpm](https://github.com/KusionStack/kpm) is a tool for managing kcl packages. This article will guide you how to use kpm in GitHub Action to push your kcl package to OCI registry.

## Step 1: Install kpm

At first, you need to install kpm on your computer. You can follow [kpm installation document](https://kcl-lang.io/docs/user_docs/guides/package-management/installation).

## Step 2: Create a GitHub account

If you already have a GitHub account, you can skip this step.

[Sign up for a new GitHub account](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account)

## Step 3: Create a GitHub repository for your KCL package

### 1. Prepare a GitHub repository for your KCL package

You need to prepare a GitHub repository for your KCL package.

[Create a GitHub repository](https://docs.github.com/en/get-started/quickstart/create-a-repo)

In this repository, add your KCL program, take the repository https://github.com/awesome-kusion/catalog.git as an example,

```bash
├── .github
│ └── workflows
│ └── push.yaml # github action workflow
├── LICENSE
├── README.md
├── kcl.mod # kcl.mod to define your kcl package
├── kcl.mod.lock # kcl.mod.lock generated by kpm
└── main.k # Your KCL program
```

### 2. Set OCI Registry, account and password for your Github repository

Take docker.io as an example, you can set secrets `REG`, `REG_ACCOUNT` and `REG_TOKEN` for your repository. The value of `REG` is `docker.io`, the value of `REG_ACCOUNT` is your `docker.io` account, and the value of `REG_TOKEN` is your `docker.io` login password.

[Add secrets to the repository](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository)

If you use `ghcr.io` as `Registry`, you need to use GitHub token as secrets.

[Create a GitHub Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#personal-access-tokens-classic)

## Step 4: Add your KCL package to the repository and write github action workflow

Add github action file `.github/workflows/push.yml` to this repository, the content is as follows:

```yaml
name: KPM Push Workflow

on:
push:
branches:
- main

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2

- name: Set up Go 1.19
uses: actions/setup-go@v2
with:
go-version: 1.19

- name: Install kpm
run: go install kcl-lang.io/kpm@latest

- name: Login and Push
env:
KPM_REG: ${{ secrets.REG }}
KPM_REPO: ${{ secrets.REG_ACCOUNT }}
run: kpm login -u ${{ secrets.REG_ACCOUNT }} -p ${{ secrets.REG_TOKEN }} ${{ secrets.REG }} && kpm push

- name: Run kpm project from oci registry
run: kpm run oci://${{ secrets.REG }}/${{ secrets.REG_ACCOUNT }}/catalog --tag 0.0.1

```
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"label": "How to",
"position": 4
}
Original file line number Diff line number Diff line change
Expand Up @@ -26,4 +26,8 @@ Please ensure that the following dependencies are in your PATH:

+ `clang` for MacOS
+ `gcc` for Linux
+ `cl.exe` for Windows, which can be obtained by installing MSVC
+ `cl.exe` for Windows, which can be obtained by installing `MSVC`

## Encountering exit status 0xc0000135 error on Windows platform

Please ensure that .NET Framework and MSVC are installed on your Windows. If not installed, you can install them and try again.

0 comments on commit 3fa168f

Please sign in to comment.