xmake-io / xmake-docs Goto Github PK

Is your feature request related to a problem? Please describe.

首先，目前API手册中的包依赖管理部分仍然写着敬请期待，但实际上已经在别的地方写了
其次，目前的位置有些难找，而且这种涉及API内容最好集中在一起，方便查看

Describe the solution you'd like

移动这部分内容到API手册，并留下指向新位置链接

Describe alternatives you've considered

No response

Additional context

No response

Is your feature request related to a problem? Please describe.

xmake-io/xmake#2374 describes how to embed rules in package, but current document about this part is missing.

Describe the solution you'd like

Fix format issues in existing document

Describe alternatives you've considered

No response

Additional context

No response

你在什么场景下需要该功能？

我现在正在做 xmake 的 lua-ls 的 addon,给所有的 xmake.lua 中的 api 提供 definitions 文件

repo: https://github.com/LelouchHe/xmake-luals-addon

个人感觉如果 API 的文档能把 definitions 和此处的 doc 结合起来,会更好,这样让二者是同步的

描述可能的解决方案

有几个可能的实现:

1. api 的类型定义可以从 definitions 中生成,而解释说明可以从 md 里来
   • 优点: 解释说明在 md 里写会比较好看
   • 缺点: 需要工具把二者整合
2. 把解释说明也放在 definitions 文件里,而 api 的文档直接从里面生成 md 或 html
   • 优点: 文档和 definitions 可以完全同步
   • 缺点: 注释里写 md 虽然可以,但感觉不是很直接

描述你认为的候选方案

No response

其他信息

我本人不是特别熟悉 lua 的文档生成,不知道这样做是否可行?

目前 addon 的内容生成是先通过抓取 md 的内容,然后解析

但从抓取的结果来看,有很多信息丢失,或者格式不统一,导致需要很多手工修改,甚至直接从头开始写

这样的话,如果 api 进行变动,没有很好的办法同步更新 definition

Xmake Version

025fbe9

Operating System Version and Architecture

macOS Ventura 13.2

Describe Bug

Not a bug, but improve the consistency and grammar of some of the documentation. I understand English is not the author's first language, and am submitting this issue to attach a PR to.

Expected Behavior

A clear reading experience, not:

we need not write any make-like file (xmake.lua, makefile.am, cmakelist.txt, etc.) and also build it directly.

Project Configuration

Not applicable

Additional Information and Error Logs

Not applicable

描述讨论详情

文档中没有找到在linux上怎么卸载xmake；这需要rm几个文件（xmake、xrepo），rm一个文件夹（xmake-script），复原.profile文件（删除xmake引入的一段），还比较复杂，需要一段说明

注：提问题时若使用不能用/没效果/有问题/报错此类模糊表达，但又没有根据下面的模板给出任何相关辅助信息的，将绝对不会有任何反馈。

描述问题

• 文档中的 add_packagedirs 链接错误，点击未跳转到正确的页面。
• 链接锚点是 targetadd_packagedirs，然而正确的锚点是 add_packagedirs。

期待的结果

点击后跳转到正确的页面。

错误信息

没有。

相关环境

浏览器。

其他信息

没有。

你在什么场景下需要该功能？

https://cmake.org/cmake/help/latest/manual/cmake-properties.7.html

类似cmake，xmake提供的target、option、package等也有很多get、set接口。有一个表可以看哪些property可以去执行get、set会很方便。

描述可能的解决方案

在API Manual (Script Scope)里面加一节property；或者在每个instance介绍里面加一张表介绍可设置的property

描述你认为的候选方案

No response

其他信息

No response

Translating ..., help me please! Edit this page

• Specification
• Documentation
  • Conditions
  • Global Interfaces
  • Project Target (google translate)
  • Configuration Option (google translate)
  • Plugin and Task (google translate)
  • Extension Platforms (google translate)
  • Extension Languages (google translate)
  • Project Templates (google translate)
  • Builtin Variables (google translate)
  • Builtin Modules (google translate)
  • Extension Modules (google translate)

!!! 注：提问题时若使用不能用/没效果/有问题/报错此类模糊表达，但又没有根据下面的模板给出任何相关辅助信息的，将会直接标记为 Invalid。

描述问题

Arch Linux 下AUR辅助工具yaourt已经停止开发，此项目的仓库已经标注unmaintained。

期待的结果

更新文档为yay -S xmake 或其他AUR helper。

错误信息

不适用

相关环境

不适用

其他信息

不适用

Xmake Version

4.7.3

Operating System Version and Architecture

All

Describe Bug

In the set_plat description, the link to "set_arch" goes to link "project_target?id=target_setarch" but it should be "project_target?id=targetset_arch"

Expected Behavior

Correct link

Project Configuration

No response

Additional Information and Error Logs

No response

注：如果是问题报障或者特性请求，请选择报告缺陷，特性请求模板，否则一律不回复。

描述讨论详情

目前官网只有install by powershell/bash的instruction，以及unix环境local installation的instruction，没有windows上手动安装的instruction；（xmake-installer.exe缺少自动补全功能，需要手动安装）

unix环境的安装缺少自定义文件夹的instruction；无法选择script/binary安装到哪个文件夹。

Is your feature request related to a problem? Please describe.

Using the documentation page can be frustrating when searching for information multiple times due to the search bar being located at the top of the sidebar. As users scroll down to view all the results, the search bar becomes hidden and difficult to locate again, forcing them to scroll all the way up to the top of the sidebar. This causes inconvenience and hinders the user experience.

Furthermore, this problem is compounded by the fact that users may not even be aware of the search bar's existence in the first place. For example, when I first accessed the documentation page, I completely missed the search bar as it is not immediately apparent that it is located at the top of the sidebar. Since my intention was to scroll down to browse the site, I spent several days unaware of the search bar's existence.

Describe the solution you'd like

To improve the user experience, it would be beneficial to have the search bar remain fixed at the top of the page Additionally, it may be helpful to make the search bar more prominent and visible to ensure that users are aware of its existence, for example by adding a search bar icon.

Describe alternatives you've considered

not really any, fixing the search bar position should be straight forward

Additional context

The search bar I'm referring to if it wasn't clear.

It would be interesting and useful for consultation in an offline environment during development.

Xmake 版本

xmake v2.7.6+master.eda07a2a7

操作系统版本和架构

22H2(22631.1265)

描述问题

当通过win11默认终端(powershell5.2)安装xmake时，即执行

Invoke-Expression (Invoke-Webrequest 'https://xmake.io/psget.text' -UseBasicParsing).Content

时，发生错误：

换用powershell7则正常：

无法解析的地方看起来像是一个三元表达式，而正好powershell7才提供三元表达式这个新特性：

期待的结果

所以我觉得，要么需要在官网注明需要用powershell7来执行，要么需要把这段三元表达式改写成powershell5兼容的语法。

工程配置

No response

附加信息和错误日志

No response

你在什么场景下需要该功能？

在Gentoo中安装xmake

描述可能的解决方案

糊了一份简单的ebuild，只在amd64做过测试

# Copyright 2022 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

EAPI=8

DESCRIPTION="A cross-platform build utility based on Lua"
HOMEPAGE="https://github.com/xmake-io/xmake"
SRC_URI="https://github.com/xmake-io/xmake/releases/download/v${PV}/${PN}-v${PV}.tar.gz"

LICENSE="Apache-2.0"
SLOT="0"
KEYWORDS="~amd64"
S="${WORKDIR}"

DEPEND=""
RDEPEND="${DEPEND}"
BDEPEND=""

src_compile() {
        emake build
}

src_install() {
        emake install DESTDIR="${D}" PREFIX="/usr"
}

描述你认为的候选方案

No response

其他信息

No response

有几个问题

1. 有一些生成文件混进来了
2. 不同语言的目录层级不同，英语在根目录下，汉语却在 zh cn 两个文件夹
3. 单个文件太长，编辑困难，能否分成多个文件，在生成 html 时再进行合并

注：提问题时若使用不能用/没效果/有问题/报错此类模糊表达，但又没有根据下面的模板给出任何相关辅助信息的，将绝对不会有任何反馈。

描述问题

在文档 https://xmake.io/#/zh-cn/manual/project_target?id=targetadd_files中

此接口使用方式跟add_installfiles接口几乎完全一样，都可以用来天剑安装文件，不过此接口仅用于安装头文件。 因此，使用上比add_installfiles简化了不少，默认不设置prefixdir，也会自动将头文件安装到对应的include子目录中。

期待的结果

可能应当为

此接口使用方式跟add_installfiles接口几乎完全一样，都可以用来添加安装文件，不过此接口仅用于安装头文件。 因此，使用上比add_installfiles简化了不少，默认不设置prefixdir，也会自动将头文件安装到对应的include子目录中。

注：如果是问题报障或者特性请求，请选择报告缺陷，特性请求模板，否则一律不回复。

描述讨论详情

xmake-io/xmake#1337

这个功能用的环境变量，在文档里面没写，要找issue才找得到，太隐蔽了

Xmake Version

4.7.3

Operating System Version and Architecture

All

Describe Bug

In the set_plat description, the link to "set_toolchains" goes to link "project_target?id=target_settoolchains" but it should be "project_target?id=targetset_toolchains"

Expected Behavior

Correct link

Project Configuration

No response

Additional Information and Error Logs

No response

切换为中方后，搜索出来的条目地址是英文的，不知道应该报在哪里，就在这里报错了。

Is your feature request related to a problem? Please describe.

In package/local_3rd_source_library.md, there are instructions for wrapping a CMake-based library from a local directory as an xmake package and then integrating this within our main project.

Describe the solution you'd like

Would it be possible to upload this (and maybe other) example packages so that users can work from them and work out how to copy the structure for a real package? Alternatively, it may make sense to change the example to use a real library that is available online (e.g. how we use things like liblzma, libpng in other examples). Then I could clone this package and try the code with my xmake project myself.

Describe alternatives you've considered

No response

Additional context

The reason I ask is that the library I need to wrap is not so simple. It would help to see have the example foo package and its CMakeLists to see what xmake is doing behind the scenes, and then see what I need to change to ensure I wrap my dependency properly. I think this might be useful for others given that CMake is a very large ecosystem now, and part of the reason I am switching to xmake is because there are too many ways to do the same thing and it becomes as hard to maintain as the code itself.

Xmake Version

4.7.3

Operating System Version and Architecture

All

Describe Bug

in the introduction it says

Xmake ~= Make/Ninja + CMake/Meson + Vcpkg/Conan + distcc + ccache/sccache

because xmake uses lua and in lua syntax ~= means ”is not”, this makes this line pretty confusing and I think we should remove the ~

Expected Behavior

not confusing

Project Configuration

No response

Additional Information and Error Logs

No response

你在什么场景下需要该功能？

类似 https://cmake.org/cmake/help/latest/manual/cmake-env-variables.7.html

希望有一个表说明xmake中用到的环境变量（xmake-repo包用到的除外），以便查询、排错

Xmake 版本

无关。

操作系统版本和架构

无关。

描述问题

xmake-docs/zh-cn/manual/conditions.md文件的is_plat接口介绍中有错字，原文如下：
如果指定的平台名不存在，就会自动切到cross平台进行交叉编译，但是缺可以通过is_plat("other")来判断自己的平台逻辑。

其次，英文文档和中文文档不一致，缺少相关内容。

期待的结果

”但是缺“应改为“但是却”，修改后如下：
如果指定的平台名不存在，就会自动切到cross平台进行交叉编译，但是却可以通过is_plat("other")来判断自己的平台逻辑。

工程配置

无关。

附加信息和错误日志

无关。

Xmake Version

v2.8.9+20240324

Operating System Version and Architecture

Windows 10 LTSC 21H2 v19044.2965

Describe Bug

    -p PLAT, --plat=PLAT                   Compile for the given platform. (default: auto)
                                               - android
                                               - appletvos
                                               - applexros
                                               - bsd
                                               - cross
                                               - cygwin
                                               - haiku
                                               - iphoneos
                                               - linux
                                               - macosx
                                               - mingw
                                               - msys
                                               - wasm
                                               - watchos
                                               - windows

Expected Behavior

Show the platforms available on the executable that are not described in the documentation.

Project Configuration

N/A

Additional Information and Error Logs

N/A