Skip to content

Documentation updated for cpp modules and cross compilation #212

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Documentation updated for cpp modules and cross compilation #212

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b1d476c
Documentation updated for cpp modules and cross compilation
mccakit May 5, 2025
16ade33
img fix
mccakit May 5, 2025
835f504
fixed indent, condensed documentation
mccakit May 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added assets/img/guide/cross_vm.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
151 changes: 97 additions & 54 deletions guide/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,6 @@ $ xmake

The `--qt` parameter setting is optional, usually xmake can detect the sdk path of qt.


One thing to note is that there is a correspondence between the versions of Emscripten and Qt SDK. If the version does not match, there may be compatibility issues between Qt/Wasm.

Regarding the version correspondence, you can see: [https://wiki.qt.io/Qt_for_WebAssembly](https://wiki.qt.io/Qt_for_WebAssembly)
Expand All @@ -114,7 +113,6 @@ $ xmake f -p wasm --toolchain=wasi
$ xmake
```


### Apple WatchOS

```bash
Expand Down Expand Up @@ -295,9 +293,55 @@ We can also configure some additional compilation and linking options through `-
e.g:

```bash
$ xmake f -p cross --sdk=/usr/toolsdk --cflags="-DTEST -I/xxx/xxx" --ldflags="-lpthread"
$ xmake f -p cross --sdk=/usr/toolsdk --cflags="-DTEST -I/xxx/xxx" --ldflags="-lpthread" 
```

### Step by Step Cross Compilation Tutorial

#### Introduction

Cross-compilation is the process of compiling code for a target architecture that differs from the one on your local machine. To do this, you must compile your source files for the desired target architecture and link them against the appropriate system libraries, typically provided through an SDK or sysroot.

#### Why Cross Compile?

* Native compilation isn’t always feasible, especially in fields like embedded systems development

* Cross-compiling on a powerful development machine is often much faster than compiling directly on the target device

* Relying solely on native compilation is impractical—there are many operating systems and architectures, and you can’t realistically own and maintain 20 different machines just to support them all

#### How do you cross compile on xmake?

1. Use a toolchain that supports cross-compilation.

2. Set the platform to `cross` and specify the target triplet using the `--cross` parameter

3. Provide the appropriate SDK or sysroot using the `--sdk` parameter

#### Example

In this example, you'll use cross compilation to run a hello world on a debian mint virtual machine. I'm assuming your host compiler is on windows.

##### Fixing the cross compilation on Windows

```bash
$ xmake update -s github:Arthapz/xmake#cakit-branch
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think to better to wait until the patch is merged within xmake codebase

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, in the current state cross compilation and modules don't work on windows, people need to be informed.

I could indicate that this is for windows more sharply if you want

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand, Arthapz has already submitted a PR to fix cross compilation on llvm, it can wait until it is merged. And I doubt that ruki will accept telling users to install a patch from a fork that will quickly fall behind the commit on xmake.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doc can be updated again on 3.0.0, this is just temporary solution. Though other parts of the tutorial are relevant without that patch.

We can just remove the update command from the doc in 3.0.0


##### Putting it together

```bash
$ xmake config --plat=cross --cross=x86_64-pc-linux-gnu --toolchain=llvm --sdk=C:/
dev/sysroots/deb2
$ wsl
$ file ./build/cross/x86_64/release/foo
./foo: ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.
so.2, for GNU/Linux 3.2.0, not stripped
```

Let's test it in our virtual machine
![loading-ag-2634](../assets/img/guide/cross_vm.png)

### Project description settings

#### set_toolchains
Expand Down Expand Up @@ -599,51 +643,51 @@ $ xmake

### Common Cross-compilation configuration

| Configuration Option | Description |
| ---------------------------- | -------------------------------------------- |
| [--sdk](#-sdk) | Set the sdk root directory of toolchains |
| [--bin](#-bin) | Set the `bin` directory of toolchains |
| [--cross](#-cross) | Set the prefix of compilation tools |
| [--as](#-as) | Set `asm` assembler |
| [--cc](#-cc) | Set `c` compiler |
| [--cxx](#-cxx) | Set `c++` compiler |
| [--mm](#-mm) | Set `objc` compiler |
| [--mxx](#-mxx) | Set `objc++` compiler |
| [--sc](#-sc) | Set `swift` compiler |
| [--gc](#-gc) | Set `golang` compiler |
| [--dc](#-dc) | Set `dlang` compiler |
| [--rc](#-rc) | Set `rust` compiler |
| [--cu](#-cu) | Set `cuda` compiler |
| [--ld](#-ld) | Set `c/c++/objc/asm` linker |
| [--sh](#-sh) | Set `c/c++/objc/asm` shared library linker |
| [--ar](#-ar) | Set `c/c++/objc/asm` static library archiver |
| [--scld](#-scld) | Set `swift` linker |
| [--scsh](#-scsh) | Set `swift` shared library linker |
| [--gcld](#-gcld) | Set `golang` linker |
| [--gcar](#-gcar) | Set `golang` static library archiver |
| [--dcld](#-dcld) | Set `dlang` linker |
| [--dcsh](#-dcsh) | Set `dlang` shared library linker |
| [--dcar](#-dcar) | Set `dlang` static library archiver |
| [--rcld](#-rcld) | Set `rust` linker |
| [--rcsh](#-rcsh) | Set `rust` shared library linker |
| [--rcar](#-rcar) | Set `rust` static library archiver |
| [--cu-ccbin](#-cu-ccbin) | Set `cuda` host compiler |
| [--culd](#-culd) | Set `cuda` linker |
| [--asflags](#-asflags) | Set `asm` assembler option |
| [--cflags](#-cflags) | Set `c` compiler option |
| [--cxflags](#-cxflags) | Set `c/c++` compiler option |
| [--cxxflags](#-cxxflags) | Set `c++` compiler option |
| [--mflags](#-mflags) | Set `objc` compiler option |
| [--mxflags](#-mxflags) | Set `objc/c++` compiler option |
| [--mxxflags](#-mxxflags) | Set `objc++` compiler option |
| [--scflags](#-scflags) | Set `swift` compiler option |
| [--gcflags](#-gcflags) | Set `golang` compiler option |
| [--dcflags](#-dcflags) | Set `dlang` compiler option |
| [--rcflags](#-rcflags) | Set `rust` compiler option |
| [--cuflags](#-cuflags) | Set `cuda` compiler option |
| [--ldflags](#-ldflags) | Set linker option |
| [--shflags](#-shflags) | Set shared library linker option |
| [--arflags](#-arflags) | Set static library archiver option |
| Configuration Option | Description |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't modify irrelevant things

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't explicity try to change those, its just that my markdown editor autoformats

| ------------------------ | -------------------------------------------- |
| [--sdk](#-sdk) | Set the sdk root directory of toolchains |
| [--bin](#-bin) | Set the `bin` directory of toolchains |
| [--cross](#-cross) | Set the prefix of compilation tools |
| [--as](#-as) | Set `asm` assembler |
| [--cc](#-cc) | Set `c` compiler |
| [--cxx](#-cxx) | Set `c++` compiler |
| [--mm](#-mm) | Set `objc` compiler |
| [--mxx](#-mxx) | Set `objc++` compiler |
| [--sc](#-sc) | Set `swift` compiler |
| [--gc](#-gc) | Set `golang` compiler |
| [--dc](#-dc) | Set `dlang` compiler |
| [--rc](#-rc) | Set `rust` compiler |
| [--cu](#-cu) | Set `cuda` compiler |
| [--ld](#-ld) | Set `c/c++/objc/asm` linker |
| [--sh](#-sh) | Set `c/c++/objc/asm` shared library linker |
| [--ar](#-ar) | Set `c/c++/objc/asm` static library archiver |
| [--scld](#-scld) | Set `swift` linker |
| [--scsh](#-scsh) | Set `swift` shared library linker |
| [--gcld](#-gcld) | Set `golang` linker |
| [--gcar](#-gcar) | Set `golang` static library archiver |
| [--dcld](#-dcld) | Set `dlang` linker |
| [--dcsh](#-dcsh) | Set `dlang` shared library linker |
| [--dcar](#-dcar) | Set `dlang` static library archiver |
| [--rcld](#-rcld) | Set `rust` linker |
| [--rcsh](#-rcsh) | Set `rust` shared library linker |
| [--rcar](#-rcar) | Set `rust` static library archiver |
| [--cu-ccbin](#-cu-ccbin) | Set `cuda` host compiler |
| [--culd](#-culd) | Set `cuda` linker |
| [--asflags](#-asflags) | Set `asm` assembler option |
| [--cflags](#-cflags) | Set `c` compiler option |
| [--cxflags](#-cxflags) | Set `c/c++` compiler option |
| [--cxxflags](#-cxxflags) | Set `c++` compiler option |
| [--mflags](#-mflags) | Set `objc` compiler option |
| [--mxflags](#-mxflags) | Set `objc/c++` compiler option |
| [--mxxflags](#-mxxflags) | Set `objc++` compiler option |
| [--scflags](#-scflags) | Set `swift` compiler option |
| [--gcflags](#-gcflags) | Set `golang` compiler option |
| [--dcflags](#-dcflags) | Set `dlang` compiler option |
| [--rcflags](#-rcflags) | Set `rust` compiler option |
| [--cuflags](#-cuflags) | Set `cuda` compiler option |
| [--ldflags](#-ldflags) | Set linker option |
| [--shflags](#-shflags) | Set shared library linker option |
| [--arflags](#-arflags) | Set static library archiver option |

<p class="tip">
if you want to known more options, please run: `xmake f --help`。
Expand Down Expand Up @@ -862,7 +906,6 @@ $ xmake f --menu --export=/tmp/config.txt
$ xmake f --menu -m debug --xxx=y --export=/tmp/config.txt
```


### Import configuration (with menu)

```bash
Expand Down Expand Up @@ -950,11 +993,11 @@ export XMAKE_ROOT=y

Currently, these values ​​can be set:

| Value | Description |
| --- | --- |
| nocolor | Disable color output |
| color8 | 8-color output support |
| color256 | 256 color output support |
| Value | Description |
| --------- | ------------------------- |
| nocolor | Disable color output |
| color8 | 8-color output support |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and here

| color256 | 256 color output support |
| truecolor | True color output support |

Generally, users don't need to set them, Xmake will automatically detect the color range supported by the user terminal. If the user doesn't want to output colors, they can set nocolor to disable them globally.
Expand Down
51 changes: 40 additions & 11 deletions guide/project_examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -313,6 +313,7 @@ $ xmake f --qt=[target Qt sdk] --qt_host=[host Qt sdk]
```

**Important considerations**:

- Make sure the host and target Qt versions match, or it may cause build issues.
- Native deployment tools like `windeployqt` and `macdeployqt` must run on their respective platforms, so cross-platform tasks such as `xmake install` may fail.

Expand Down Expand Up @@ -628,11 +629,11 @@ $ xmake l private.tools.codesign.dump
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>AppIDName</key>
<string>XC org tboox test</string>
<key>ApplicationIdentifierPrefix</key>
<array>
<string>43AAQM58X3</string>
<key>AppIDName</key>
<string>XC org tboox test</string>
<key>ApplicationIdentifierPrefix</key>
<array>
<string>43AAQM58X3</string>
...
```

Expand Down Expand Up @@ -1106,12 +1107,12 @@ main.rs

```rust
extern "C" {
fn add(a: i32, b: i32) -> i32;
fn add(a: i32, b: i32) -> i32;
}

fn main() {
unsafe {
println!("add(1, 2) = {}", add(1, 2));
println!("add(1, 2) = {}", add(1, 2));
}
}
```
Expand Down Expand Up @@ -1466,7 +1467,7 @@ package("foo")
on_install(function(package)
import("package.tools.xmake").install(package, {})
end)
````
```

#### Integrating the C++ Modules package

Expand Down Expand Up @@ -1560,6 +1561,37 @@ It is still possible to experiment with xmake to build std modules in lower vers

For a discussion see: [#3255](https://github.com/xmake-io/xmake/pull/3255)

##### Hello, Modules – A Step-by-Step Walkthrough

1. Install the llvm toolchain, compiling manually is recommended, make sure you have libcxx installed

2. Patch your llvm toolchain,by cloning this [repo](https://github.com/mccakit/xmake_llvm_patch) and putting its contents to C:\llvm\share\libc++\v1\std
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here too, there is too much Windows-specific stuff, and a lot of it is based on third-party repositories.


3. Update your xmake installation to a branch that fixes modules and cross compilation for windows with

```bash
$ xmake update -s github:Arthapz/xmake#cakit-branch
```

4. Enable cpp modules in your xmake.lua file

```lua
set_languages("cxxlatest")
set_policy("build.c++.modules", true)
```

5. Build and enjoy the results

```cpp
import std;
```

```bash
$ xmake f --toolchain=llvm --runtimes="c++_shared" --sdk=C:/llvm
$ xmake build
Hi
```

#### Gcc

It is not currently supported.
Expand Down Expand Up @@ -1880,7 +1912,6 @@ $ xmake -v
WARNING: modpost: Symbol info of vmlinux is missing. Unresolved symbol check will be entirely skipped.
/usr/bin/ccache /usr/bin/gcc -c -m64 -O2 -std=gnu89 -I/usr/src/linux-headers-5.11.0-41-generic/arch/x86/include -I/usr /src/linux-headers-5.11.0-41-generic/arch/x86/include/generated -I/usr/src/linux-headers-5.11.0-41-generic/include -I/usr/src/linux -headers-5.11.0-41-generic/arch/x86/include/uapi -I/usr/src/linux-headers-5.11.0-41-generic/arch/x86/include/generated/uapi -I/usr /src/linux-headers-5.11.0-41-generic/include/uapi -I/usr/src/linux-headers-5.11.0-41-generic/include/generated/uapi -D__KERNEL__ -DMODULE -DKBUILD_MODNAME=\"hello\" -DCONFIG_X86_X32_ABI -isystem /usr/lib/gcc/x86_64-linux-gnu/10/include -include /usr/src/linux-headers- 5.11.0-41-generic/include/linux/kconfig.h -include /usr/src/linux-headers-5.11.0-41-generic/include/linux/compiler_types.h -nostdinc -mno-sse -mno- mmx -mno-sse2 -mno-3dnow -mno-avx -mno-80387 -mno-fp-ret-in-387 -mpreferred-stack-boundary=3 -mskip-rax-setup -mtune=generic -mno-red- zone -mcmodel=kernel -mindirect-branch=thunk-extern -mindirect-branch-register -mrecord-mcount -fmacro-prefix-map=./= -fno-strict-aliasing -fno-common -fshort-wchar -fno- PIE -fcf-protection=none -falign-jumps=1 -falign-loops=1 -fno-asynchronous-unwind-tables -fno-jump-tables -fno-delete-null-pointer-checks -fno-allow-store- data-races -fno-reorder-blocks -fno-ipa-cp-clone -fno-partial-inlining -fstack-protector-strong -fno-inline-functions-called-once -falign-functions=32 -fno-strict- overflow -fno-stack-check -fconserve-stack -o build/.o bjs/hello/linux/x86_64/release/build/linux/x86_64/release/hello.ko.mod.o build/.objs/hello/linux/x86_64/release/build/linux/x86_64/release/hello.ko. mod.c
/usr/bin/ld -m elf_x86_64 -r --build-id=sha1 -T /usr/src/linux-headers-5.11.0-41-generic/scripts/module.lds -o build/linux/x86_64/ release/hello.ko build/.objs/hello/linux/x86_64/release/build/linux/x86_64/release/hello.ko.o build/.objs/hello/linux/x86_64/release/build/linux/x86_64/ release/hello.ko.mod.o

```

Through the `add_requires("linux-headers", {configs = {driver_modules = true}})` configuration package, xmake will automatically find the corresponding linux-headers package from the system first.
Expand Down Expand Up @@ -1967,7 +1998,6 @@ WARNING: modpost: Symbol info of vmlinux is missing. Unresolved symbol check wil
/usr/bin/ccache /mnt/gcc-linaro-7.5.0-2019.12-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf-gcc -c -O2 -std=gnu89 -I/home/ruki/. xmake/packages/l/linux-headers/5.10.46/7695a30b7add4d3aa4685cbac6815805/arch/arm/include -I/home/ruki/.xmake/packages/l/linux-headers/5.10.46/7695a30b7add4d3aa4685cbac6815805/arch/arm/include /generated -I/home/ruki/.xmake/packages/l/linux-headers/5.10.46/7695a30b7add4d3aa4685cbac6815805/include -I/home/ruki/.xmake/packages/l/linux-headers/5.10.46/7695a30b7add4d3aa4685cbac6815805 /arch/arm/include/uapi -I/home/ruki/.xmake/packages/l/linux-headers/5.10.46/7695a30b7add4d3aa4685cbac6815805/arch/arm/include/generated/uapi -I/home/ruki/.xmake /packages/l/linux-headers/5.10.46/7695a30b7add4d3aa4685cbac6815805/include/uapi -I/home/ruki/.xmake/packages/l/linux-headers/5.10.46/7695a30b7add4d3aa4685cbac6815805/include/generated/uapi -D__KERNEL__ DMODULE -DKBUILD_MODNAME=\"hello\" -D__LINUX_ARM_ARCH__=6 -isystem /mnt/gcc-linaro-7.5.0-2019.12-x86_64_arm-linux-gnueabihf /bin/../lib/gcc/arm-linux-gnueabihf/7.5.0/include -include /home/ruki/.xmake/packages/l/linux-headers/5.10.46/7695a30b7add4d3aa4685cbac6815805/include/linux/kconfig .h -include /home/ruki/.xmake/packages/l/linux-headers/5.10.46/7695a30b7add4d3aa4685cbac6815805/include/linux/compiler_types.h -nostdinc -fno-strict-aliasing -fno-common -fshort-wchar- fno-PIE -falign-jumps=1 -falign-loops=1 -fno-asynchronous-unwind-tables -fno-jump-tables -fno-delete-null-pointer-checks -fno-reorder-blocks -fno-ipa- cp-clone -fno-partial-inlining -fstack-protector-strong -fno-inline-functions-called-once -falign-functions=32 -fno-strict-overflow -fno-stack-check -fconserve-stack -mbig- endian -mabi=aapcs-linux -mfpu=vfp -marm -march=armv6k -mtune=arm1136j-s -msoft-float -Uarm -o build/.objs/hello/cross/arm/release/build/cross/arm/ release/hello.ko.mod.o build/.objs/hello/cross/arm/release/build/cross/arm/release/hello.ko.mod.c
/mnt/gcc-linaro-7.5.0-2019.12-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf-ld -EB --be8 -r --build-id=sha1 -T /home/ruki/. xmake/packages/l/linux-headers/5.10.46/7695a30b7add4d3aa4685cbac6815805/scripts/module.lds -o build/cross/arm/release/hello.ko build/.objs/hello/cross/arm/release/build/cross /arm/release/hello.ko.o build/.objs/hello/cross/arm/release/build/cross/arm/release/hello.ko.mod.o
[100%]: build ok!

```

#### Build Arm64 driver module
Expand Down Expand Up @@ -2061,7 +2091,6 @@ Currently supported values and mappings are as follows:

#### Set custom flags


```lua
add_requires("iverilog")
target("hello")
Expand Down