add getting started

docs/.vitepress/config.mts

@@ -31,44 +31,6 @@ export default defineConfig({
   themeConfig: {
     logo: { src: '/assets/img/logo.svg', width: 24, height: 24 },
 
-    nav: [
-    {
-        text: 'Docs',
-        activeMatch: `^/(guide|style-guide|cookbook|examples)/`,
-        items: [
-          { text: 'Guide', link: '/guide/introduction' },
-          { text: 'Examples', link: '/examples/' },
-          { text: 'Quick Start', link: '/guide/quick-start' },
-          { text: 'API Reference', link: '/api/' }
-        ]
-      },
-      { text: 'Sponsor', link: '/about/sponsor' }
-    ],
-
-    sidebar: [
-      {
-        text: 'Examples',
-        items: [
-          { text: 'Markdown Examples', link: '/markdown-examples' },
-          { text: 'Runtime API Examples', link: '/test1' },
-          { text: 'Runtime API Examples', link: '/test2' },
-          { text: 'Runtime API Examples', link: '/test3' },
-          { text: 'Runtime API Examples', link: '/test4' },
-          { text: 'Runtime API Examples', link: '/test5' },
-          { text: 'Runtime API Examples', link: '/test6' },
-          { text: 'Runtime API Examples', link: '/test7' },
-          { text: 'Runtime API Examples', link: '/test8' },
-          { text: 'Runtime API Examples', link: '/test9' },
-          { text: 'Runtime API Examples', link: '/api-examples' }
-        ]
-      }
-    ],
-
-    editLink: {
-      pattern: 'https://github.com/xmake-io/xmake-docs/edit/master/docs/:path',
-      text: 'Edit this page on GitHub'
-    },
-
     socialLinks: [
       { icon: 'github', link: 'https://github.com/xmake-io/xmake' },
       { icon: 'twitter', link: 'https://twitter.com/waruqi' },

docs/guide/getting-started.md

@@ -1 +1,296 @@
-# Getting started
+---
+outline: deep
+---
+
+# Installation
+
+::: tip NOTE
+Xmake is not recommended to install under root!
+:::
+
+::: code-group
+
+```bash [curl]
+curl -fsSL https://xmake.io/shget.text | bash
+```
+
+```bash [wget]
+wget https://xmake.io/shget.text -O - | bash
+```
+
+```powershell [powershell]
+Invoke-Expression (Invoke-Webrequest 'https://xmake.io/psget.text' -UseBasicParsing).Content
+```
+
+:::
+
+If you want to install a specific version and branch, you can append the version number and branch parameters later
+
+```bash
+curl -fsSL https://xmake.io/shget.text | bash -s dev
+curl -fsSL https://xmake.io/shget.text | bash -s v2.7.7
+```
+
+If you want to install a specific version and branch, you can append the version number and branch parameters later
+
+```powershell
+Invoke-Expression (Invoke-Webrequest 'https://xmake.io/psget.text' -UseBasicParsing).Content dev
+Invoke-Expression (Invoke-Webrequest 'https://xmake.io/psget.text' -UseBasicParsing).Content v2.7.7
+```
+
+::: tip NOTE
+If the ps script execution prompt fails, you can try to execute in administrator mode.
+:::
+
+## Windows
+
+### via installer
+
+1. Download the Xmake windows installer from [Releases](https://github.com/xmake-io/xmake/releases)
+2. Run xmake-[version].[win32|win64].exe
+
+::: tip NOTE
+Releases/xmake-[version].[win32|win64].zip has not installer, we need unzip it and add PATH environment variables by ourself.
+:::
+
+In addition, the installation package with `xmake-tinyc-xxx.exe`, which integrates the tinyc compiler environment, and comes with libc and winapi header files. By installing this package, you can compile c programs normally without msvc.
+This is very useful for users who want to write some c tests or algorithm codes temporarily, but don't want to install msvc, but the installation package will be slightly larger than 2-3M.
+
+::: code-group
+
+```bash [scoop]
+scoop install xmake
+```
+
+```bash [winget]
+winget install xmake
+```
+:::
+
+## Msys/Mingw
+
+::: code-group
+
+```bash [mingw64]
+pacman -Sy mingw-w64-x86_64-xmake
+```
+
+```bash [mingw32]
+pacman -Sy mingw-w64-i686-xmake
+```
+
+:::
+
+## MacOS
+
+```bash
+ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+brew install xmake
+```
+
+## Linux distributions
+
+::: code-group
+
+```bash [Archlinux]
+sudo pacman -Sy xmake
+```
+
+```bash [Alpine]
+sudo apk add xmake
+```
+
+```bash [ubuntu]
+sudo apt install xmake
+```
+
+```bash [debian]
+sudo apt install xmake
+```
+
+```bash [fedora]
+sudo dnf install xmake
+```
+
+:::
+
+## Ubuntu
+
+### Install PPA packages
+
+```bash
+sudo add-apt-repository ppa:xmake-io/xmake
+sudo apt update
+sudo apt install xmake
+```
+
+Also, Xmake has recently been added to the official Debian repositories: https://packages.debian.org/sid/xmake
+
+## Gentoo
+
+1. Refer to [here](https://wiki.gentoo.org/wiki/Project:GURU/Information_for_End_Users) to add GURU to your system repository
+2. Install dev-util/xmake
+
+```bash
+sudo emerge -a --autounmask dev-util/xmake
+```
+
+## Other Linux
+
+Download xmake `xmake-x.x.x.gz.run` install package from [Releases](https://github.com/xmake-io/xmake/releases) 
+
+```bash
+sudo chmod 777 ./xmake-x.x.x.gz.run
+./xmake-x.x.x.gz.run
+```
+
+## FreeBSD
+
+Due to package name conflicts, only xmake-io can be used as the package name.
+
+```bash
+pkg install xmake-io
+```
+
+## Termux (Android)
+
+```bash
+pkg install xmake
+```
+
+## Bundle package
+
+If you don't want to install, we also provide another Bundle packaging format, which does not require user installation, a single executable file, can be run and used after downloading, and is easy to distribute.
+
+It will build all Lua scripts into the Xmake executable file, without the need for additional installation and configuration of any environment variables.
+
+We can get them from [Releases](https://github.com/xmake-io/xmake/releases), and there are currently some Bundle packages as follows.
+
+```
+xmake-bundle-v2.9.8.arm64.exe
+xmake-bundle-v2.9.8.cosmocc
+xmake-bundle-v2.9.8.linux.x86_64
+xmake-bundle-v2.9.8.macos.arm64
+xmake-bundle-v2.9.8.macos.x86_64
+xmake-bundle-v2.9.8.win32.exe
+xmake-bundle-v2.9.8.win64.exe
+```
+
+Among them, the package with the `.cosmocc` suffix provides the ability to run across platforms, but the support for Windows is still relatively weak, and it is not recommended to use it on Windows.
+
+The others are single executable files for specific platforms, and users can download and use them as needed according to their own systems.
+
+## Source compilation and installation
+ 
+### Installation
+
+```bash
+git clone --recursive https://github.com/xmake-io/xmake.git
+cd ./xmake
+# On macOS, you may need to run: export SDKROOT=$(xcrun --sdk macosx --show-sdk-path)
+./configure
+make
+./scripts/get.sh __local__ __install_only__
+source ~/.xmake/profile
+```
+
+If you think the source of github is too slow, you can pull it through the mirror source of gitee or gitlab: 
+
+```bash
+git clone --recursive https://gitee.com/tboox/xmake.git
+git clone --recursive https://gitlab.com/tboox/xmake.git
+```
+
+::: tip NOTE
+Since the current Xmake source maintains dependencies via git submodule, it is necessary to add the `--recursive` parameter to pull all submodules at the same time. Please do not download the tar.gz source directly, because github does not automatically package submodules. Code.
+:::
+
+If you forget to add `--recursive` when git clone, you can also execute `git submodule update --init` to pull all submodules, for example:
+
+```bash
+git clone https://github.com/xmake-io/xmake.git
+cd ./xmake
+git submodule update --init
+./configure
+make
+./scripts/get.sh __local__ __install_only__
+```
+
+::: tip NOTE
+`./get.sh __local__` is installed to `~/.local/xmake`, and then loaded by `source ~/.xmake/profile`, so after the installation, the current terminal fails to execute Xmake, If the prompt is not found, manually execute `source ~/.xmake/profile`, and the next time you open the terminal, you don't need it.
+:::
+
+### Source compilation in Windows platform
+
+```bash
+git clone --recursive https://github.com/xmake-io/xmake.git
+cd ./xmake/core
+xmake
+```
+
+### Only update the lua script
+
+This developer needs to debug the Xmake source locally:
+
+```bash
+./scripts/get.sh __local__ __install_only__
+```
+
+### Root installation
+
+Xmake is not recommended for root installation, because this is very insecure. If the user has to download the root, if the prompt Xmake fails to run, please pass the `--root` parameter as prompted or set `XMAKE_ROOT=y`. The environment variable is forcibly enabled, provided that the user needs to pay attention to the risk of incorrect operating system file files under root.
+
+### Dependency issues
+
+1. If you encounter problems with readline, please install readline-devel or libreadline-dev dependencies. This is optional. It is only needed when the `xmake lua` command executes REPL.
+2. If you want to speed up compilation, you can install ccache, Xmake will automatically detect and use, which is also optional.
+
+## Other installation methods
+
+::: tip NOTE
+This is also the source code compilation and installation, but the installation path will be written directly to `/usr/`, which requires root privileges, so unless special circumstances, this installation method is not recommended, it is recommended to use the `./get. Sh __local__` way to install, the installation path of the two installation methods is different, do not mix.
+:::
+
+Compile and install via make:
+
+```bash
+./configure
+make
+sudo make install
+```
+
+Install to other specified directories:
+
+```bash
+sudo make install PREFIX=/usr/local
+```
+
+## Update Upgrade
+
+Starting with v2.2.3, the `xmake update` command has been added to quickly update and upgrade itself. The default is to upgrade to the latest version. Of course, you can also specify to upgrade or roll back to a version:
+
+```bash
+xmake update 2.7.1
+```
+
+We can also specify an update to the master/dev branch version:
+
+```bash
+xmake update master
+xmake update dev
+```
+
+Update from the specified git source
+
+```bash
+xmake update github:xmake-io/xmake#master
+xmake update gitee:tboox/xmake#dev # gitee mirror
+```
+
+If just update the xmake lua script changes, you can add `-s/--scriptonly` to quickly update the lua script.
+
+```bash
+xmake update -s dev
+```
+
+Finally, if we want to uninstall Xmake, we're sorry to see you go! Still, it is supported: `xmake update --uninstall`.

docs/guide/what-is-xmake.md

@@ -1 +1,9 @@
 # What is Xmake?
+
+Xmake is a lightweight cross-platform build utility based on Lua. It uses a Lua script to maintain project builds, but is driven by a dependency free core program written in C. Compared with Makefiles or CMake, the configuration syntax is much concise and intuitive. As such, it's friendly to novices while still maintaining the flexibly required in a build system. With Xmake, you can focus on your project instead of the build.
+
+Xmake can be used to directly build source code (like with Make or Ninja), or it can generate project source files like CMake or Meson. It also has a *built-in* package management system to help users integrate C/C++ dependencies.
+
+If you want to know more, please refer to: the [Documentation](https://xmake.io/guide/getting-started.html), [GitHub](https://github.com/xmake-io/xmake) or [Gitee](https://gitee.com/tboox/xmake). You are also welcome to join our [community](https://xmake.io/#/about/contact).
+
+![](https://xmake.io/assets/img/index/xmake-basic-render.gif)

docs/public/psget.text

@@ -0,0 +1,17 @@
+#!/usr/bin/env pwsh
+#Requires -version 5
+
+# Use this extension for correct Content-Type
+
+param (
+  [string]$version = "master",
+  [string]$installdir = ""
+)
+
+& {
+  $getscript = (Invoke-Webrequest 'https://fastly.jsdelivr.net/gh/xmake-io/xmake@master/scripts/get.ps1' -UseBasicParsing).Content
+  if ($getscript -is [Byte[]]) {
+    $getscript = [System.Text.Encoding]::UTF8.GetString($getscript)
+  }
+  & $([System.Management.Automation.ScriptBlock]::Create($getscript)) $version $installdir
+}

docs/public/robots.txt

@@ -0,0 +1,3 @@
+User-Agent: *
+Allow: /
+Sitemap: https://xmake.io/sitemap.xml

docs/public/shget.text

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+remote_get_content() {
+    if curl --version >/dev/null 2>&1
+    then
+        curl -fsSL "$1"
+    elif wget --version >/dev/null 2>&1
+    then
+        wget "$1" -O -
+    fi
+}
+
+bash <(remote_get_content https://fastly.jsdelivr.net/gh/xmake-io/xmake@dev/scripts/get.sh) $@

docs/zh/guide/getting-started.md

@@ -1 +1,319 @@
-# 快速上手
+---
+outline: deep
+---
+
+# 安装
+
+::: tip 注意
+切记，xmake不建议在root下安装和使用，所以尽量不要在root下拉取源码编译安装！
+:::
+
+::: code-group
+
+```bash [curl]
+curl -fsSL https://xmake.io/shget.text | bash
+```
+
+```bash [wget]
+wget https://xmake.io/shget.text -O - | bash
+```
+
+```powershell [powershell]
+Invoke-Expression (Invoke-Webrequest 'https://xmake.io/psget.text' -UseBasicParsing).Content
+```
+
+如果要安装指定版本和分支，后面可以追加版本号和分支参数
+
+```bash
+curl -fsSL https://xmake.io/shget.text | bash -s dev
+curl -fsSL https://xmake.io/shget.text | bash -s v2.7.7
+```
+
+如果要安装指定版本和分支，后面可以追加版本号和分支参数
+
+```powershell
+Invoke-Expression (Invoke-Webrequest 'https://xmake.io/psget.text' -UseBasicParsing).Content dev
+Invoke-Expression (Invoke-Webrequest 'https://xmake.io/psget.text' -UseBasicParsing).Content v2.7.7
+```
+
+::: tip 注意
+如果ps脚本执行提示失败，可以尝试在管理员模式下执行
+:::
+
+## Windows
+
+### 使用安装包
+
+1. 从 [Releases](https://github.com/xmake-io/xmake/releases) 上下载windows安装包
+2. 运行安装程序 xmake-[version].[win32|win64].exe
+
+::: tip 注意
+Releases 下面 xmake-[version].[win32|win64].zip 的包是不带安装程序的，可直接解压使用，绿色无依赖，不过需要自己添加PATH环境变量。
+:::
+
+另外，Releases下面带有 xmake-tinyc 开头的exe安装包，内部集成了 tinyc 编译器环境，自带 libc 和 winapi 头文件，安装这个包，可以实现在没有 msvc 环境下，也能正常编译 c 程序。
+这对于临时想写一些 c 测试或者算法代码，又不想安装 msvc 的用户非常有用，不过安装包会稍微大2-3M，不过也还好。
+
+::: code-group
+
+```bash [scoop]
+scoop install xmake
+```
+
+```bash [winget]
+winget install xmake
+```
+:::
+
+## Msys/Mingw
+
+现在msys/pacman官方仓库已经收录xmake软件包，可直接通过pacman安装。
+
+::: code-group
+
+```bash [mingw64]
+pacman -Sy mingw-w64-x86_64-xmake
+```
+
+```bash [mingw32]
+pacman -Sy mingw-w64-i686-xmake
+```
+
+:::
+
+## MacOS
+
+```bash
+ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+brew install xmake
+```
+
+或者：
+
+1. 从 [Releases](https://github.com/xmake-io/xmake/releases) 上下载pkg安装包
+2. 双击运行
+
+或者安装master版本:
+
+```bash
+# 使用homebrew安装master版本
+brew install xmake --HEAD
+
+# 或者直接调用shell下载安装
+bash <(curl -fsSL https://xmake.io/shget.text)
+```
+
+## Linux 发行版
+
+
+::: code-group
+
+```bash [Archlinux]
+sudo pacman -Sy xmake
+```
+
+```bash [Alpine]
+sudo apk add xmake
+```
+
+```bash [ubuntu]
+sudo apt install xmake
+```
+
+```bash [debian]
+sudo apt install xmake
+```
+
+```bash [fedora]
+sudo dnf install xmake
+```
+
+:::
+
+## Ubuntu
+
+### 安装 PPA 包
+
+```bash
+sudo add-apt-repository ppa:xmake-io/xmake
+sudo apt update
+sudo apt install xmake
+```
+
+另外，近期 Xmake 已经被收入到 Debian 官方仓库：https://packages.debian.org/sid/xmake
+
+## Gentoo
+
+1. 参考[这里](https://wiki.gentoo.org/wiki/Project:GURU/Information_for_End_Users)将GURU添加到你的系统仓库
+2. 安装dev-util/xmake
+
+```bash
+sudo emerge -a --autounmask dev-util/xmake
+```
+
+## 其他 Linux
+
+先从 [Releases](https://github.com/xmake-io/xmake/releases) 上下载xmake-x.x.x.gz.run自安装包
+
+然后运行这个自安装包。
+
+```bash
+sudo chmod 777 ./xmake-x.x.x.gz.run
+./xmake-x.x.x.gz.run
+```
+
+## FreeBSD
+
+由于 BSD 上，已有的 xmake 包名已被占用，只能使用 xmake-io 作为包名来安装。
+
+```bash
+pkg install xmake-io
+```
+
+## Termux (Android)
+
+```bash
+pkg install xmake
+```
+
+## Bundle 包
+
+如果不想安装，我们也提供了另外一种 Bundle 打包格式，它无需用户安装，单一可执行文件，下载即可运行使用，方便分发。
+
+它会把所有 Lua 脚本内置到 Xmake 可执行文件中去，不需要额外安装和配置什么环境变量。
+
+我们可以到 [Releases](https://github.com/xmake-io/xmake/releases) 中获取它们，目前有如下一些 Bundle 包。
+
+```
+xmake-bundle-v2.9.8.arm64.exe
+xmake-bundle-v2.9.8.cosmocc
+xmake-bundle-v2.9.8.linux.x86_64
+xmake-bundle-v2.9.8.macos.arm64
+xmake-bundle-v2.9.8.macos.x86_64
+xmake-bundle-v2.9.8.win32.exe
+xmake-bundle-v2.9.8.win64.exe
+```
+
+其中，`.cosmocc` 后缀的包，提供了跨平台运行的能力，但是目前对 Windows 上支持还比较弱，不推荐在 windows 上使用。
+
+另外的都是针对特定平台的单一可执行文件，用户根据自己的系统按需下载使用。
+
+
+## 源码编译安装
+
+### 安装
+
+::: tip 注意
+切记，xmake不建议在root下安装和使用，所以尽量不要在root下拉取源码编译安装！
+:::
+
+```bash
+git clone --recursive https://github.com/xmake-io/xmake.git
+cd ./xmake
+./configure
+make
+./scripts/get.sh __local__ __install_only__
+source ~/.xmake/profile
+```
+
+如果觉得github的源太慢，可以通过gitee的镜像源拉取：`clone --recursive https://gitee.com/tboox/xmake.git`
+也可以如下修改~/.gitconfig，永久解决github clone慢的问题
+```
+[url "ssh://[email protected]/"]
+  insteadOf = https://github.com/
+```
+
+::: tip 注意
+由于目前xmake源码通过git submodule维护依赖，所以clone的时候需要加上`--recursive`参数同时拉取所有submodules代码，请不要直接下载tar.gz源码，因为github不会自动打包submodules里面的代码。
+:::
+
+如果git clone的时候忘记加`--recursive`，那么也可以执行`git submodule update --init`来拉取所有submodules，例如：
+
+```bash
+git clone https://github.com/xmake-io/xmake.git
+cd ./xmake
+git submodule update --init
+./configure
+make
+./scripts/get.sh __local__ __install_only__
+```
+
+::: tip 注意
+`./get.sh __local__`是安装到`~/.local/xmake`下，然后通过`source ~/.xmake/profile`方式来加载的，所以安装完，当前终端如果执行xmake失败，提示找不到，就手动执行下 `source ~/.xmake/profile`，而下次打开终端就不需要了。
+:::
+
+### Windows 平台源码安装
+
+```bash
+git clone --recursive https://github.com/xmake-io/xmake.git
+cd ./xmake/core
+xmake
+```
+
+### 仅仅更新安装lua脚本
+
+这个开发者本地调试xmake源码才需要：
+
+```bash
+./scripts/get.sh __local__ __install_only__
+```
+
+### root下安装
+
+xmake不推荐root下安装使用，因为这很不安全，如果用户非要root下装，装完后，如果提示xmake运行不了，请根据提示传递`--root`参数，或者设置`XMAKE_ROOT=y`环境变量强行启用下，前提是：用户需要随时注意root下误操作系统文件文件的风险。
+
+### 依赖问题
+
+1. 如果遇到readline相关问题，请装下readline-devel或者libreadline-dev依赖，这个是可选的，仅仅`xmake lua`命令执行REPL时候才需要。
+2. 如果想要提速编译，可以装下ccache，xmake会自动检测并使用，这也是可选的。
+
+## 其他安装方式
+
+::: tip 注意
+这种也是源码编译安装，但是安装路径会直接写入`/usr/`下，需要root权限，因此除非特殊情况，不推荐这种安装方式，建议采用上文提供的`./get.sh __local__`方式来安装，这两种安装方式的安装路径是不同的，不要混用。
+:::
+
+通过make进行编译安装:
+
+```bash
+./configure
+make
+sudo make install
+```
+
+安装到其他指定目录:
+
+```bash
+sudo make install PREFIX=/usr/local
+```
+
+## 更新升级
+
+从v2.2.3版本开始，新增了`xmake update`命令，来快速进行自我更新和升级，默认是升级到最新版本，当然也可以指定升级或者回退到某个版本：
+
+```bash
+xmake update 2.7.1
+```
+
+我们也可以指定更新到master/dev分支版本：
+
+```bash
+xmake update master
+xmake update dev
+```
+
+从指定git源更新
+
+```bash
+xmake update github:xmake-io/xmake#master
+xmake update gitee:tboox/xmake#dev # gitee镜像
+```
+
+如果xmake/core没动过，仅仅更新xmake的lua脚本改动，可以加`-s/--scriptonly`快速更新lua脚本
+
+```bash
+xmake update -s dev
+```
+
+最后，我们如果要卸载xmake，也是支持的：`xmake update --uninstall`
+

docs/zh/guide/what-is-xmake.md

@@ -1 +1,11 @@
 # 什么是 Xmake?
+
+xmake 是一个基于 Lua 的轻量级跨平台构建工具，使用 xmake.lua 维护项目构建，相比 makefile/CMakeLists.txt，配置语法更加简洁直观，对新手非常友好，短时间内就能快速入门，能够让用户把更多的精力集中在实际的项目开发上。
+
+虽然，简单易用是 xmake 的一大特色，但 xmake 的功能也是非常强大的，既能够像 Make/Ninja 那样可以直接编译项目，也可以像 CMake/Meson 那样生成工程文件，还有内置的包管理系统来帮助用户解决 C/C++依赖库的集成使用问题。
+
+目前，xmake主要用于C/C++项目的构建，但是同时也支持其他native语言的构建，可以实现跟C/C++进行混合编译，同时编译速度也是非常的快，可以跟Ninja持平。
+
+如果你想要了解更多，请参考：[在线文档](https://xmake.io/zh/guide/getting-started.html), [Github](https://github.com/xmake-io/xmake)以及[Gitee](https://gitee.com/tboox/xmake)，同时也欢迎加入我们的 [社区](https://xmake.io/#/zh-ch/about/contact).
+
+![](https://xmake.io/assets/img/index/xmake-basic-render.gif)