gen_esb Binary Tool Usage

gen_esb is a binary tool used to generate ES API code. It reads the operator-prototype .so files located in the op_graph subdirectory of the CANN software package, as determined by the ASCEND_OPP_PATH environment variable, and produces the corresponding ES artifacts based on the prototype information contained in those .so files. When using a custom op_proto prototype .so, you are advised to use the add_es_library function provided by generate_es_package.cmake to generate and compile the ES artifacts. The generated products are as follows:

C APIs of all supported operators
C++ APIs of all supported operators
Python APIs of all supported operators
Aggregation header file, which allows you to include all operators at a time
Aggregation Python file, which allows you to include all operators at a time.

Prerequisites

Before using this tool, install the CANN software package. After the installation is complete, the tool is installed in the ${INSTALL_DIR}/bin directory. Replace ${INSTALL_DIR} with the CANN component directory. For example, if the installation is performed by the root user, the default file storage path is /usr/local/Ascend/cann.
Set environment variables. (In the following example, the CANN software package is installed in the default path by the root user.)
1
source /usr/local/Ascend/cann/set_env.sh

After the preceding steps are complete, run gen_esb --help in any path on the server locating the CANN software package. If information similar to the following is displayed, the tool is running properly:

==========================================
ES Graph Builder Code Generator v1.0
Copyright (c) 2025 Huawei Technologies Co., Ltd.
==========================================

ES Graph Builder Code Generator v1.0
Usage: ./gen_esb [--output_dir=DIR] [--module_name=NAME] [--h_guard_prefix=PREFIX] [--exclude_ops=OP_TYPE]
... ...

Example and Parameters

Command for using the tool:

./gen_esb [--output_dir=DIR] [--module_name=NAME] [--h_guard_prefix=PREFIX] [--exclude_ops=OP_TYPE1,OP_TYPE2]

Parameters

--(Optional) output_dir: specifies the target directory for code generation. If this parameter is not specified, the code is generated in the current directory by default.
--(Optional) module_name: specifies the name of the aggregation header file.
- "math" -> es_math_ops_c.h, es_math_ops.h, es_math_ops.py
- "all" -> es_all_ops_c.h, es_all_ops.h, es_all_ops.py
- If no value is passed, all is used by default.
--(Optional) h_guard_prefix: specifies the prefix of the protection macro of the generated header file. It distinguishes internal and external operators with the same name (if possible).
- If this parameter is not specified, the default prefix is used.
- If this parameter is specified, the default prefix is concatenated.
- The Python file does not detect this parameter. Different paths are used to avoid conflicts in this case.
--(Optional) exclude_ops: specifies operators that cannot be generated. Operator names are separated with commas (,).

The sample is as follows:

Generate the file to the current directory, use the default name all for the file name, and use the default prefix for macro protection.
```
./gen_esb
```
Generate the file to the specified directory, use the default name all for the file name, and use the default prefix for macro protection.
```
./gen_esb --output_dir=./output
```
Generate the file to the specified directory, use math for the file name, and use the default prefix for macro protection.
```
./gen_esb --output_dir=./output --module_name=math
```
Generate the file to the specified directory, use all for the file name, and use the default prefix for macro protection.
```
./gen_esb --output_dir=./output --module_name=all
```
Generate the file to the specified directory, use math for the file name, and use MY_CUSTOM as the macro protection prefix.
```
./gen_esb --output_dir=./output --module_name=math --h_guard_prefix=MY_CUSTOM
```
Generate the file to the specified directory, use math for the file name, use MY_CUSTOM as the macro protection prefix, and exclude the Add operator.
```
./gen_esb --output_dir=./output --module_name=math --h_guard_prefix=MY_CUSTOM --exclude_ops=Add
```

Output Files

es_{module_name}_ops_c.h: C interface aggregation header file
es_{module_name}_ops.h: C++ API aggregation header file
es_{module_name}_ops.py: Python API aggregation file
es_<op_type>_c.h: C API header file of a single operator
es_<op_type>.cpp: C API implementation file of a single operator
es_<op_type>.h: C++ API header file of a single operator
es_<op_type>.py: Python API file of a single operator

Parent topic: Appendix