From 4a370b5f41550f93ebfada6e1d068be435920ff4 Mon Sep 17 00:00:00 2001 From: peefy Date: Mon, 18 Sep 2023 21:03:16 +0800 Subject: [PATCH] feat: add more install trouble shooting messages on windows platforms --- docs/user_docs/getting-started/install.md | 2 + docs/user_docs/support/faq-install.md | 6 +- .../user_docs/getting-started/install.md | 2 + .../current/user_docs/support/faq-install.md | 8 +- .../user_docs/getting-started/install.md | 2 + .../user_docs/support/faq-install.md | 8 +- .../user_docs/getting-started/install.md | 2 + .../4-how-to/4-share_your_pkg.md | 73 +++++++++++++++++ .../4-how-to/5-share_your_pkg_docker.md | 63 ++++++++++++++ .../4-how-to/6-push_github_action.md | 82 +++++++++++++++++++ .../4-how-to/_category_.json | 4 + .../user_docs/support/faq-install.md | 6 +- 12 files changed, 252 insertions(+), 6 deletions(-) create mode 100644 versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/4-share_your_pkg.md create mode 100644 versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/5-share_your_pkg_docker.md create mode 100644 versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/6-push_github_action.md create mode 100644 versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/_category_.json diff --git a/docs/user_docs/getting-started/install.md b/docs/user_docs/getting-started/install.md index db93664e..ec0c61eb 100644 --- a/docs/user_docs/getting-started/install.md +++ b/docs/user_docs/getting-started/install.md @@ -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 diff --git a/docs/user_docs/support/faq-install.md b/docs/user_docs/support/faq-install.md index aca616f6..8c363f73 100644 --- a/docs/user_docs/support/faq-install.md +++ b/docs/user_docs/support/faq-install.md @@ -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. diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/getting-started/install.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/getting-started/install.md index 31ef2e18..e93de3a1 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/getting-started/install.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/getting-started/install.md @@ -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 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/support/faq-install.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/support/faq-install.md index f64581f8..3e6bb341 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/support/faq-install.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/support/faq-install.md @@ -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，如没有安装，可以安装并重试 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.6.0/user_docs/getting-started/install.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.6.0/user_docs/getting-started/install.md index 31ef2e18..e93de3a1 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.6.0/user_docs/getting-started/install.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.6.0/user_docs/getting-started/install.md @@ -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 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.6.0/user_docs/support/faq-install.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.6.0/user_docs/support/faq-install.md index f64581f8..3e6bb341 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.6.0/user_docs/support/faq-install.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.6.0/user_docs/support/faq-install.md @@ -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，如没有安装，可以安装并重试 diff --git a/versioned_docs/version-0.6.0/user_docs/getting-started/install.md b/versioned_docs/version-0.6.0/user_docs/getting-started/install.md index db93664e..ec0c61eb 100644 --- a/versioned_docs/version-0.6.0/user_docs/getting-started/install.md +++ b/versioned_docs/version-0.6.0/user_docs/getting-started/install.md @@ -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 diff --git a/versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/4-share_your_pkg.md b/versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/4-share_your_pkg.md new file mode 100644 index 00000000..8108126a --- /dev/null +++ b/versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/4-share_your_pkg.md @@ -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 -p +``` + +Where `` is your GitHub username, `` 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). diff --git a/versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/5-share_your_pkg_docker.md b/versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/5-share_your_pkg_docker.md new file mode 100644 index 00000000..7379843a --- /dev/null +++ b/versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/5-share_your_pkg_docker.md @@ -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 -p docker.io +``` + +Where `` is your `docker.io` username, and `` 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//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). diff --git a/versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/6-push_github_action.md b/versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/6-push_github_action.md new file mode 100644 index 00000000..410b4810 --- /dev/null +++ b/versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/6-push_github_action.md @@ -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 + +``` diff --git a/versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/_category_.json b/versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/_category_.json new file mode 100644 index 00000000..e3409c62 --- /dev/null +++ b/versioned_docs/version-0.6.0/user_docs/guides/package-management/4-how-to/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "How to", + "position": 4 +} diff --git a/versioned_docs/version-0.6.0/user_docs/support/faq-install.md b/versioned_docs/version-0.6.0/user_docs/support/faq-install.md index aca616f6..8c363f73 100644 --- a/versioned_docs/version-0.6.0/user_docs/support/faq-install.md +++ b/versioned_docs/version-0.6.0/user_docs/support/faq-install.md @@ -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.