diff --git a/en/device-dev/subsystems/subsys-build-all.md b/en/device-dev/subsystems/subsys-build-all.md index a7111d5c13621490a871197a5e55f7bcb6ff3c43..027d2a10128a551e7681dde628b84360fba35a8e 100644 --- a/en/device-dev/subsystems/subsys-build-all.md +++ b/en/device-dev/subsystems/subsys-build-all.md @@ -122,7 +122,9 @@ You must install the software packages required for build. The command is as fol # export PATH=~/.local/bin:$PATH ``` - >**NOTE**
The hb tool will be installed during the installation of **ohos-build**. If hb tool fails to be installed, [install hb](../../device-dev/quick-start/quickstart-pkg-install-tool.md#hb-installation) again. + >**NOTE** + > + >The hb tool will be installed during the installation of **ohos-build**. If hb tool fails to be installed, [install hb](../../device-dev/quick-start/quickstart-pkg-install-tool.md#hb-installation) again. ## Configuration Rules @@ -133,6 +135,7 @@ To ensure that chipset and product solutions are decoupled from OpenHarmony, you - [Subsystem Configuration Rules](subsys-build-subsystem.md#configuration-rules) - [Component Configuration Rules](subsys-build-component.md#configuration-rules) - [Module Configuration Rules](subsys-build-module.md#configuration-rules) +- [Rust Module Configuration Rules](subsys-build-rust-compilation.md#configuration-rules) - [Chipset Solution Configuration Rules](subsys-build-chip_solution.md#configuration-rules) - [Feature Configuration Rules](subsys-build-feature.md#configuration-rules) - [System Capability Configuration Rules](subsys-build-syscap.md) @@ -172,10 +175,10 @@ misc/ ├── scripts/ ├── subsystem_config.json ├── subsystem_config_example.json -├── templates/ # C/C++ build templates +├── templates/ # C/C++ build templates ├── test.gni* -├── toolchain # Build toolchain configuration -├── tools # Common tools +├── toolchain # Build toolchain configuration +├── tools # Common tools ├── version.gni ├── zip.py* @@ -195,171 +198,181 @@ Then, run the build commands in command line (CLI) mode or hb mode. 1. Using the CLI -- Run the following command in the root directory of the source code to build a full distribution: - - Release version: - ```shell - ./build.sh --product-name {product_name} - ``` - Debug version: - ```shell - ./build.sh --product-name {product_name} --gn-args is_debug=true - ``` - > **CAUTION**
- > Due to the limitation of the image size, the full build for the debug version may fail to be burnt. You are advised to build the binary file for each module separately. Run the following command to build a module separately: - > - > - > ``` - > ./build.sh --product-name {product_name} --gn-args is_debug=true --build-target {target_name} - > ``` - > - **{product_name}** specifies the product platform supported by the current distribution, for example, **hispark_taurus_standard**. - - The image generated is stored in the **out/{device_name}/packages/phone/images/** directory. - - - -- The **./build.sh** command supports the following options: - - ```shell - -h, --help # Display help information and exit. - --source-root-dir=SOURCE_ROOT_DIR # Specify the path. - --product-name=PRODUCT_NAME # Specify the product name. - --device-name=DEVICE_NAME # Specify the device name. - --target-cpu=TARGET_CPU # Specify the CPU. - --target-os=TARGET_OS # Specify the operating system. - -T BUILD_TARGET, --build-target=BUILD_TARGET # Specify one or more targets to build. - --gn-args=GN_ARGS # Specify GN parameters. - --ninja-args=NINJA_ARGS # Specify Ninja parameters. - -v, --verbose # Display all commands used. - --keep-ninja-going # Keep Ninja going until 1,000,000 jobs fail. - --jobs=JOBS - --export-para=EXPORT_PARA - --build-only-gn # Perform GN parsing and do not run Ninja. - --ccache # (Optional) Use ccache for build. You need to install ccache locally. - --fast-rebuild # Specify whether to allow fast rebuild. The default value is False. - --log-level=LOG_LEVEL # Specify the log level used in the build process. The options are debug, info, and error. The default value is info. - --device-type=DEVICE_TYPE # Specify the device type. The default value is default. - --build-variant=BUILD_VARIANT #Specify the device operation mode. The default value is user. - ``` + - Run the following command in the root directory of the source code to build a full distribution: + + Release version: + + ```shell + ./build.sh --product-name {product_name} + ``` + + Debug version: + + ```shell + ./build.sh --product-name {product_name} --gn-args is_debug=true + ``` + + > **CAUTION** + > + > Due to the limitation of the image size, the full build for the debug version may fail to be burnt. You are advised to build the binary file for each module separately. Run the following command to build a module separately: + > + > ``` + > ./build.sh --product-name {product_name} --gn-args is_debug=true --build-target {target_name} + > ``` + > + > **{product_name}** specifies the product platform supported by the current distribution, for example, **hispark_taurus_standard**. + > + > The image generated is stored in the **out/{device_name}/packages/phone/images/** directory. + + - The **./build.sh** command supports the following options: + + ```shell + -h, --help # Display help information and exit. + --source-root-dir=SOURCE_ROOT_DIR # Specify the path. + --product-name=PRODUCT_NAME # Specify the product name. + --device-name=DEVICE_NAME # Specify the device name. + --target-cpu=TARGET_CPU # Specify the CPU. + --target-os=TARGET_OS # Specify the operating system. + -T BUILD_TARGET, --build-target=BUILD_TARGET # Specify one or more targets to build. + --gn-args=GN_ARGS # Specify GN parameters. + --ninja-args=NINJA_ARGS # Specify Ninja parameters. + -v, --verbose # Display all commands used. + --keep-ninja-going # Keep Ninja going until 1,000,000 jobs fail. + --jobs=JOBS + --export-para=EXPORT_PARA + --build-only-gn # Perform GN parsing and do not run Ninja. + --ccache # (Optional) Use ccache for build. You need to install ccache locally. + --fast-rebuild # Specify whether to allow fast rebuild. The default value is False. + --log-level=LOG_LEVEL # Specify the log level used in the build process. The options are debug, info, and error. The default value is info. + --device-type=DEVICE_TYPE # Specify the device type. The default value is default. + --build-variant=BUILD_VARIANT #Specify the device operation mode. The default value is user. + ``` + + 2. Using the hb tool -**hb** is an OpenHarmony command line tool for executing build commands. Common hb commands are described as follows: - -**hb set** - -Sets the product to build. - -```shell -hb set -h -usage: hb set [-h] [-root [ROOT_PATH]] [-p] - -optional arguments: - -h, --help show this help message and exit - -root [ROOT_PATH], --root_path [ROOT_PATH] - Set OHOS root path - -p, --product Set OHOS board and kernel -``` - -- If you run **hb set** with no argument, the default setting process starts. - -- You can run **hb set -root** *dir* to set the root directory of the source code. - -- You can run **hb set -p** to set the product to build. + **hb** is an OpenHarmony command line tool for executing build commands. Common hb commands are described as follows: -**hb env** + **hb set** -Displays current settings. + Sets the product to build. -```shell -hb env -[OHOS INFO] root path: xxx -[OHOS INFO] board: hispark_taurus -[OHOS INFO] kernel: liteos -[OHOS INFO] product: ipcamera -[OHOS INFO] product path: xxx/vendor/hisilicon/ipcamera -[OHOS INFO] device path: xxx/device/hisilicon/hispark_taurus/sdk_linux_4.19 -``` - -**hb build** + ```shell + hb set -h + usage: hb set [-h] [-root [ROOT_PATH]] [-p] + + optional arguments: + -h, --help show this help message and exit + -root [ROOT_PATH], --root_path [ROOT_PATH] + Set OHOS root path + -p, --product Set OHOS board and kernel + ``` -Builds a product, component, module, or chipset solution. + - If you run **hb set** with no argument, the default setting process starts. -```shell -hb build -h -usage: hb build [-h] [-b BUILD_TYPE] [-c COMPILER] [-t [TEST [TEST ...]]] [-cpu TARGET_CPU] [--dmverity] [--tee] - [-p PRODUCT] [-f] [-n] [-T [TARGET [TARGET ...]]] [-v] [-shs] [--patch] [--compact-mode] - [--gn-args GN_ARGS] [--keep-ninja-going] [--build-only-gn] [--log-level LOG_LEVEL] [--fast-rebuild] - [--device-type DEVICE_TYPE] [--build-variant BUILD_VARIANT] - [component [component ...]] - -positional arguments: - component name of the component, mini/small only - -optional arguments: - -h, --help show this help message and exit - -b BUILD_TYPE, --build_type BUILD_TYPE - release or debug version, mini/small only - -c COMPILER, --compiler COMPILER - specify compiler, mini/small only - -t [TEST [TEST ...]], --test [TEST [TEST ...]] - compile test suit - -cpu TARGET_CPU, --target-cpu TARGET_CPU - select cpu - --dmverity enable dmverity - --tee Enable tee - -p PRODUCT, --product PRODUCT - build a specified product with {product_name}@{company} - -f, --full full code compilation - -n, --ndk compile ndk - -T [TARGET [TARGET ...]], --target [TARGET [TARGET ...]] - compile single target - -v, --verbose show all command lines while building - -shs, --sign_haps_by_server - sign haps by server - --patch apply product patch before compiling - --compact-mode compatible with standard build system set to false if we use build.sh as build entrance - --gn-args GN_ARGS specifies gn build arguments, eg: --gn-args="foo="bar" enable=true blah=7" - --keep-ninja-going keeps ninja going until 1000000 jobs fail - --build-only-gn only do gn parse, do not run ninja - --log-level LOG_LEVEL - specifies the log level during compilationyou can select three levels: debug, info and error - --fast-rebuild it will skip prepare, preloader, gn_gen steps so we can enable it only when there is no change - for gn related script - --device-type DEVICE_TYPE - specifies device type - --build-variant BUILD_VARIANT - specifies device operating mode -``` + - You can run **hb set -root** *dir* to set the root directory of the source code. -- If you run **hb build** with no argument, the previously configured code directory, product, and options are used for the build. The **-f** option deletes all products to be built. It is equivalent to running **hb clean** and **hb build**. + - You can run **hb set -p** to set the product to build. -- You can run **hb build** *{component_name}* to build product components separately based on the development board and kernel set for the product, for example, **hb build kv_store**. + -- You can run **hb build -p ipcamera@hisilicon** to skip the setting step and build the product directly. + **hb env** -- You can run **hb build** in **device/board/device_company** to select the kernel and build an image that contains the kernel and drivers only based on the current development board and the selected kernel. + Displays current settings. -**hb clean** + ```shell + hb env + [OHOS INFO] root path: xxx + [OHOS INFO] board: hispark_taurus + [OHOS INFO] kernel: liteos + [OHOS INFO] product: ipcamera + [OHOS INFO] product path: xxx/vendor/hisilicon/ipcamera + [OHOS INFO] device path: xxx/device/hisilicon/hispark_taurus/sdk_linux_4.19 + ``` -Deletes all the files except **args.gn** and **build.log** in the **out** directory (default). To clear files in a specified directory, add the directory parameter to the command, for example, **hb clean out/board/product**. + -```shell -hb clean -usage: hb clean [-h] [out_path] + **hb build** -positional arguments: - out_path clean a specified path. + Builds a product, component, module, or chipset solution. -optional arguments: - -h, --help show this help message and exit -``` + ```shell + hb build -h + usage: hb build [-h] [-b BUILD_TYPE] [-c COMPILER] [-t [TEST [TEST ...]]] [-cpu TARGET_CPU] [--dmverity] [--tee] + [-p PRODUCT] [-f] [-n] [-T [TARGET [TARGET ...]]] [-v] [-shs] [--patch] [--compact-mode] + [--gn-args GN_ARGS] [--keep-ninja-going] [--build-only-gn] [--log-level LOG_LEVEL] [--fast-rebuild] + [--device-type DEVICE_TYPE] [--build-variant BUILD_VARIANT] + [component [component ...]] + + positional arguments: + component name of the component, mini/small only + + optional arguments: + -h, --help show this help message and exit + -b BUILD_TYPE, --build_type BUILD_TYPE + release or debug version, mini/small only + -c COMPILER, --compiler COMPILER + specify compiler, mini/small only + -t [TEST [TEST ...]], --test [TEST [TEST ...]] + compile test suit + -cpu TARGET_CPU, --target-cpu TARGET_CPU + select cpu + --dmverity enable dmverity + --tee Enable tee + -p PRODUCT, --product PRODUCT + build a specified product with {product_name}@{company} + -f, --full full code compilation + -n, --ndk compile ndk + -T [TARGET [TARGET ...]], --target [TARGET [TARGET ...]] + compile single target + -v, --verbose show all command lines while building + -shs, --sign_haps_by_server + sign haps by server + --patch apply product patch before compiling + --compact-mode compatible with standard build system set to false if we use build.sh as build entrance + --gn-args GN_ARGS specifies gn build arguments, eg: --gn-args="foo="bar" enable=true blah=7" + --keep-ninja-going keeps ninja going until 1000000 jobs fail + --build-only-gn only do gn parse, do not run ninja + --log-level LOG_LEVEL + specifies the log level during compilationyou can select three levels: debug, info and error + --fast-rebuild it will skip prepare, preloader, gn_gen steps so we can enable it only when there is no change + for gn related script + --device-type DEVICE_TYPE + specifies device type + --build-variant BUILD_VARIANT + specifies device operating mode + ``` + + - If you run **hb build** with no argument, the previously configured code directory, product, and options are used for the build. The **-f** option deletes all products to be built. It is equivalent to running **hb clean** and **hb build**. + + - You can run **hb build** *{component_name}* to build product components separately based on the development board and kernel set for the product, for example, **hb build kv_store**. + + - You can run **hb build -p ipcamera@hisilicon** to skip the setting step and build the product directly. + + - You can run **hb build** in **device/board/device_company** to select the kernel and build an image that contains the kernel and drivers only based on the current development board and the selected kernel. + + + + **hb clean** + + Deletes all the files except **args.gn** and **build.log** in the **out** directory (default). To clear files in a specified directory, add the directory parameter to the command, for example, **hb clean out/board/product**. + + ```shell + hb clean + usage: hb clean [-h] [out_path] + + positional arguments: + out_path clean a specified path. + + optional arguments: + -h, --help show this help message and exit + ``` -> **NOTE** -> -> - For details about how to set up the build environment and perform the build, see the related topics in [Getting Started](../quick-start/quickstart-overview.md) -> - OpenHarmony also provides the Docker environment, which spares the installation of the build tool. For details, see [Docker Environment](../get-code/gettools-acquire.md) + > **NOTE** + > + > - For details about how to set up the build environment and perform the build, see the related topics in [Getting Started](../quick-start/quickstart-overview.md). + > - OpenHarmony also provides the Docker environment, which spares the installation of the build tool. For details, see [Docker Environment](../get-code/gettools-acquire.md). ### Building Procedures @@ -382,3 +395,4 @@ You can add and build a product, component, chipset solution, and module. For de - [Parameters for Accelerating Local Build](subsys-build-reference.md#parameters-for-accelerating-local-build) - [Viewing Ninja Build Information](subsys-build-reference.md#viewing-ninja-build-information) - [Customizing the chip_prod Image](subsys-build-reference.md#customizing-the-chip_prod-image) + diff --git a/en/device-dev/subsystems/subsys-build-cargo2gn-guide.md b/en/device-dev/subsystems/subsys-build-cargo2gn-guide.md index fcf8a04804809485cbaed0cee49ca467272a4caf..cf3f6b53f70de749cea6edc08882887c5a79fd24 100644 --- a/en/device-dev/subsystems/subsys-build-cargo2gn-guide.md +++ b/en/device-dev/subsystems/subsys-build-cargo2gn-guide.md @@ -14,7 +14,7 @@ When used in OpenHarmony, **Cargo.toml** needs to be converted into **BUILD.gn** 2. Create the configuration file **cargo2gn.json**. - ``` + ```json { "copy-out": true, "run": true, @@ -26,7 +26,7 @@ When used in OpenHarmony, **Cargo.toml** needs to be converted into **BUILD.gn** 3. Run the following command to perform the conversion: ``` - python /mnt/xxx/openharmony/build/scripts/cargo2gn.py --config cargo2gn.json + python3 /mnt/xxx/openharmony/build/scripts/cargo2gn.py --config cargo2gn.json ``` The conversion result is as follows: @@ -85,7 +85,7 @@ When used in OpenHarmony, **Cargo.toml** needs to be converted into **BUILD.gn** ``` 2. Add all the rust libraries to be converted to [workspace] in **Cargo.toml** in the **rust** directory. - ``` + ```toml [workspace] members = [ "aho-corasick", diff --git a/en/device-dev/subsystems/subsys-build-rust-compilation.md b/en/device-dev/subsystems/subsys-build-rust-compilation.md index b02f52d3d27110bc29f29a3fc245e92af78ed0db..b12dbb59c0f35d8f72422c2f4ca61fa980ea381e 100644 --- a/en/device-dev/subsystems/subsys-build-rust-compilation.md +++ b/en/device-dev/subsystems/subsys-build-rust-compilation.md @@ -18,7 +18,7 @@ To integrate Rust code and maximize the interaction between the C/C++ code used -## Configure Rules +## Configuration Rules OpenHarmony provides a variety of GN templates for compiling Rust executables, dynamic libraries, and static libraries. The following table describes the templates. | GN Template | Description | Output | @@ -104,7 +104,10 @@ The procedure is as follows: ![test_rlib_crate](./figures/test_rlib_crate.png) ### Configuring a Third-Party Library -The following example shows how to use the **ohos_rust_executable** and **ohos_rust_cargo_crate** templates to build a third-party static rlib library whose code contains a prebuilt file **build.rs**. + +The **BUILD.gn** file of the rust third-party library can be automatically generated using the cargo2gn tool. For details, see [Using Cargo2gn](subsys-build-cargo2gn-guide.md). + +The following example shows how to use the **ohos_rust_executable** and **ohos_rust_cargo_crate** templates to compile a third-party static library rlib file that contains a prebuilt file **build.rs**. The procedure is as follows: @@ -307,18 +310,18 @@ The procedure is as follows: You can find the Rust module configuration examples in the **build/rust/tests** directory. | Directory | Description | | -------------------------------------------- | ------------------------------------------------------------ | -| build/rust/tests/test_bin_crate | Tests the build of an executable file on the host platform and running of the executable file on the target platform. | -| build/rust/tests/test_static_link | Tests the static linking of an executable file to a standard library. | -| build/rust/tests/test_dylib_crate | Tests the build of a dynamic library and dynamic linking. | -| build/rust/tests/test_rlib_crate | Tests the build of a static library and static linking. | -| build/rust/tests/test_proc_macro_crate | Tests the build of Rust process macros and the linking function. Test cases are provided for different types of macros. | -| build/rust/tests/test_cdylib_crate | Tests the generation of Rust FFI bindings to a C/C++ dynamic library. | -| build/rust/tests/test_staticlib_crate | Tests the generation of Rust FFI bindings to a C/C++ static library. | -| build/rust/tests/test_rust_ut | Tests the Rust code unit test template. | -| build/rust/tests/test_rust_st | Tests the Rust code system test template. | -| build/rust/tests/test_bin_cargo_crate | Tests the build and running of a Rust third-party executable file. The third-party code contains the **build.rs**. | -| build/rust/tests/test_rlib_cargo_crate | Tests the build of a Rust third-party static library and static linking. The third-party code contains the **build.rs**. | -| build/rust/tests/test_proc_macro_cargo_crate | Tests the build of Rust third-party process macros and linking. The third-party code contains the **build.rs**. | +| build/rust/tests/test_bin_crate | Tests the build of an executable file on the host platform and running of the executable file on the target platform.| +| build/rust/tests/test_static_link | Tests the static linking of an executable file to a standard library. | +| build/rust/tests/test_dylib_crate | Tests the build of a dynamic library and dynamic linking. | +| build/rust/tests/test_rlib_crate | Tests the build of a static library and static linking. | +| build/rust/tests/test_proc_macro_crate | Tests the build of Rust process macros and the linking function. Test cases are provided for different types of macros.| +| build/rust/tests/test_cdylib_crate | Tests the generation of Rust FFI bindings to a C/C++ dynamic library. | +| build/rust/tests/test_staticlib_crate | Tests the generation of Rust FFI bindings to a C/C++ static library. | +| build/rust/tests/test_rust_ut | Tests the Rust code unit test template. | +| build/rust/tests/test_rust_st | Tests the Rust code system test template. | +| build/rust/tests/test_bin_cargo_crate | Tests the build and running of a Rust third-party executable file. The third-party source code contains **build.rs**.| +| build/rust/tests/test_rlib_cargo_crate | Tests the build of a Rust third-party static library and static linking. The third-party source code contains **build.rs**.| +| build/rust/tests/test_proc_macro_cargo_crate | Tests the build of Rust third-party process macros and linking. The third-party source code contains **build.rs**. | ## Reference @@ -347,6 +350,7 @@ executable("foo") { The OpenHarmony framework supports two types of lints: rustc lints and Clippy lints. Each type of lint has three levels: openharmony (highest), vendor, and none (lowest). When configuring the Rust module, you can specify the lint level in **rustc_lints** or **clippy_lints**. + If **rustc_lints** or **clippy_lints** is not configured in the module, the lint level is matched based on the module path. Different restrictions apply to the syntax specifications of Rust code in different directories. Therefore, you need to pay attention to the path of the module when configuring the Rust module to build in OpenHarmony. #### Levels of rustc Lints and Clippy Lints @@ -367,3 +371,6 @@ If **rustc_lints** or **clippy_lints** is not configured in the module, the lint | vendor | vendor | | device | vendor | | others | openharmony | + +### [Interactive Tool User Guide](subsys-build-bindgen-cxx-guide.md) +### [Using Cargo2gn](subsys-build-cargo2gn-guide.md)