diff --git a/assets/img/guide/cross_vm.png b/assets/img/guide/cross_vm.png new file mode 100644 index 00000000..a214ad3c Binary files /dev/null and b/assets/img/guide/cross_vm.png differ diff --git a/guide/configuration.md b/guide/configuration.md index 3d4494c4..577dc84b 100644 --- a/guide/configuration.md +++ b/guide/configuration.md @@ -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) @@ -114,7 +113,6 @@ $ xmake f -p wasm --toolchain=wasi $ xmake ``` - ### Apple WatchOS ```bash @@ -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 +``` + +##### 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 @@ -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 | +| ------------------------ | -------------------------------------------- | +| [--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 |

if you want to known more options, please run: `xmake f --help`。 @@ -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 @@ -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 | +| 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. diff --git a/guide/project_examples.md b/guide/project_examples.md index d868bdd3..b01e4c5a 100644 --- a/guide/project_examples.md +++ b/guide/project_examples.md @@ -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. @@ -628,11 +629,11 @@ $ xmake l private.tools.codesign.dump - AppIDName - XC org tboox test - ApplicationIdentifierPrefix - - 43AAQM58X3 + AppIDName + XC org tboox test + ApplicationIdentifierPrefix + + 43AAQM58X3 ... ``` @@ -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)); } } ``` @@ -1466,7 +1467,7 @@ package("foo") on_install(function(package) import("package.tools.xmake").install(package, {}) end) -```` +``` #### Integrating the C++ Modules package @@ -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 + +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. @@ -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. @@ -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 @@ -2061,7 +2091,6 @@ Currently supported values and mappings are as follows: #### Set custom flags - ```lua add_requires("iverilog") target("hello")