CANN/ge ES API生成CMake指南

add_es_library Usage Guide【免费下载链接】geGEGraph Engine是面向昇腾的图编译器和执行器提供了计算图优化、多流并行、内存复用和模型下沉等技术手段加速模型执行效率减少模型内存占用。 GE 提供对 PyTorch、TensorFlow 前端的友好接入能力并同时支持 onnx、pb 等主流模型格式的解析与编译。项目地址: https://gitcode.com/cann/geOverviewProvides the following CMake functions for generating Eager Style (ES) artifacts:add_es_library_and_whl: Generate C/C dynamic library Python wheel package (complete artifacts)add_es_library: Only generate C/C dynamic library (for pure C/C projects)Quick StartPrerequisitesProperly installtoolkitpackage via Installation Guide, andcorrectly configure environment variablesas instructedDefine prototype dynamic libraryadd_library(opgraph_math SHARED #Required to be .so form )1. Import FunctionsUsing find_package# Add module path in your CMakeLists.txt (ASCEND_HOME_PATH comes from environment variable configuration in Prerequisites) list(APPEND CMAKE_MODULE_PATH ${ASCEND_HOME_PATH}/include/ge/cmake) # Find module find_package(GenerateEsPackage REQUIRED)Note:Current version requires manually addingCMAKE_MODULE_PATHin CMakeLists.txtPlanned support: Future versions will support directfind_packageafter justsource set_env.sh(no need to manually add path)2. Generate ES APIGenerate Complete Artifactsadd_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math #Prototype library target from Prerequisites OUTPUT_PATH ${CMAKE_BINARY_DIR}/output )Only Generate C/C Libraryadd_es_library( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output )3. Use Generated Artifacts# Link in your application add_executable(my_app main.cpp) target_link_libraries(my_app PRIVATE es_math)4. Build# Just build your application directly make my_app # → Will automatically trigger ES package buildParameter DescriptionFunction ParametersBoth functions have identical parameters:ParameterRequiredDescriptionExampleES_LINKABLE_AND_ALL_TARGET✅ RequiredLibrary target name exposed externallyes_math,es_nn,es_cvOPP_PROTO_TARGET✅ RequiredOperator prototype librarys CMake target name (supports SHARED/STATIC/INTERFACE/OBJECT types)opgraph_math,opgraph_nnOUTPUT_PATH☑️ OptionalRoot directory for artifact output. If not specified, artifacts remain in build directory${CMAKE_BINARY_DIR}/outputEXCLUDE_OPS☑️ OptionalOperators to exclude from generationAdd,Conv2DDifference:add_es_library_and_whl: Generate library wheel packageadd_es_library: Only generate library (skip wheel package generation)Important:Since ES artifacts are dynamically generated inside the function, and cmake overall handles configuration and build in separate phases, our function internally has reconfiguration and build operations, which is why we currently directly provide an interface typeES_LINKABLE_AND_ALL_TARGETThe function automatically derives prototype library path fromOPP_PROTO_TARGETsLIBRARY_OUTPUT_DIRECTORY, which is the basic condition for generating ES artifacts corresponding to the prototype libraryHistorical Prototype Library Related CMake VariablesSet the following variables viaset()before calling the function to control historical prototype library functionality:VariableTypeDescriptionExampleGE_ES_EXTRACT_HISTORYbool (optional)When ON, passes--es_modeextract_historyto gen_esb, enablinghistorical prototype library generation mode(archive current prototype as JSON, for subsequent version code generation); if not set or OFF, gen_esb defaults tocodegen(only generate C API)set(GE_ES_EXTRACT_HISTORY ON)GE_ES_RELEASE_VERSIONOptionalCurrent new version number, archive step will archive current prototype as this version; must be set in historical prototype library generation modeset(GE_ES_RELEASE_VERSION 8.0.RC1)GE_ES_RELEASE_DATEOptionalSpecify release date in historical prototype library generation mode (formatYYYY-MM-DD), if not set gen_esb uses current dateset(GE_ES_RELEASE_DATE 2026-02-28)GE_ES_BRANCH_NAMEOptionalSpecify release branch name in historical prototype library generation mode.Note: When set tomaster, function ignores all archive-related variables (GE_ES_EXTRACT_HISTORY/GE_ES_RELEASE_VERSION/GE_ES_RELEASE_DATE), only runs pure code generation modeset(GE_ES_BRANCH_NAME release/8.0)Historical Prototype Library Path Auto-Derivation: Function internally auto-derives${CANN_INSTALL_PATH}/cann/opp/history_registry/modulepath based on cmake file installation location. When path exists and is non-empty, automatically passes--history_registryto gen_esb,caller doesnt need to explicitly set historical prototype library path.Complete Commercial Release Mode: WhenGE_ES_EXTRACT_HISTORYONand ops package contains historical prototype library,add_es_libraryinternally automatically executes gen_esb twice in sequence (code generation historical prototype library archivemerge),caller doesnt need extra handling. Oneadd_es_librarycall completes all operations needed for complete commercial release (see Example 11).Output ArtifactsArtifacts Generated by add_es_library_and_whlOUTPUT_PATH/ ├── include/ │ └── es_math/ # Header file directory │ ├── es_math_ops.h # C interface aggregated header file │ ├── es_math_ops_c.h # C interface aggregated header file │ └── es_add.h ... # Single operator header file (generally multiple files) ├── lib64/ │ ├── libes_math.so # Dynamic library │ └── libes_math.a # Static library └── whl/ └── es_math-1.0.0-py3-none-any.whl # Python packageArtifacts Generated by add_es_libraryOUTPUT_PATH/ ├── include/ │ └── es_math/ # Header file directory │ ├── es_math_ops.h # C interface aggregated header file │ ├── es_math_ops_c.h # C interface aggregated header file │ └── es_add.h ... # Single operator header file (generally multiple files) └── lib64/ ├── libes_math.so # Dynamic library └── libes_math.a # Static libraryNote:Aggregation meaning: Contains graph building API for all operators under es_mathDynamic and Static Libraries: Each generation produces bothlibname.soandlibname.a. External interface target (likees_math) defaults to linking dynamic library; if static linking is needed, manually specifylib64/libname.aor link static library viatarget_link_libraries(your_target PRIVATE ${OUTPUT_PATH}/lib64/libes_math.a)etc.Additional Artifacts After Enabling Historical Prototype Library Related ModesHistorical Prototype Library Generation Mode (GE_ES_EXTRACT_HISTORYON)gen_esb directly outputs toOUTPUT_PATH, generating the following JSON structure:OUTPUT_PATH/ ├── index.json # Version index (list of all archived versions) └── registry/ └── GE_ES_RELEASE_VERSION/ ├── metadata.json # Version metadata (version number, release date, branch name etc.) └── operators.json # Operator prototype data (IR structured description)Code Generation Mode with Historical Compatibility (Auto-detected Historical Prototype Library)C header files will have multi-version overload signatures for the same operator (historical version signature current version signature),.socontains implementations of all versions simultaneously, forward compatible with old version calling methods. Artifact directory structure is same as standard mode, only header file content differs.Generated TargetsTargets for External UseTarget NamePurposeDescriptiones_mathLink DependencyUsers link through this target, automatically triggers build; defaults to linking dynamic library (.so), static library (.a) also generated simultaneously. IfOUTPUT_PATHspecified, can directly get static library file fromlib64/; if not specified, remains in CMake default output directory.Usage ExamplesExample 1: Basic Usage# 1. Define prototype dynamic library (Prerequisites) add_library(opgraph_math SHARED ) # 2. Generate ES API package (library wheel package) add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output ) # 3. Use in application add_executable(my_app main.cpp) target_link_libraries(my_app PRIVATE es_math)Tip: If project has OBJECT/STATIC intermediate targets that need ES header files during compilation phase, can additionally addadd_dependencies(intermediate_target build_es_math)(build_es_***name changes with package name), to ensure code generation completes before compiling that target. Final executable or shared library just needstarget_link_libraries(... es_math)to automatically trigger related dependencies.Supplementary Example: Including Object Libraryadd_library(my_obj OBJECT foo.cc bar.cc) # Ensure es_math header files generated before compiling object (recommended to add explicitly) add_dependencies(my_obj build_es_math) # Pass header file search path effect target_link_libraries(my_obj PRIVATE es_math) add_executable(my_app $TARGET_OBJECTS:my_obj) target_link_libraries(my_app PRIVATE es_math )Example 2: Only Generate C/C Library# Only generate C/C library (skip Python wheel package) add_es_library( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output )Example 3: Exclude Partial Operator Generation# Generate math TARGET # Generated artifacts wont contain es_Add_c.h; es_Add.h, es_Add.cpp, es_Add.py add_es_library( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output EXCLUDE_OPS Add )Example 4: Using OBJECT Type Prototype Library# Define OBJECT type prototype library add_library(opgraph_math OBJECT src/math_op1.cpp src/math_op2.cpp ) # Generate ES API (function internally automatically creates temporary SHARED library wrapper) add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math # OBJECT type OUTPUT_PATH ${CMAKE_BINARY_DIR}/output )Example 5: Not Specifying OUTPUT_PATH# Not specifying OUTPUT_PATH, artifacts will remain in build directory add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math # OUTPUT_PATH not specified )Artifacts DisplayBuild artifacts remain in build directory and CMake default target output directory, wont be additionally organized into unifiedinclude/,lib64/,whl/directories.build_dir/es_math_build/ ├── generated_code/ # gen_esb and wrapper output │ ├── es_math_ops.h # C interface aggregated header file │ ├── es_math_ops_c.h # C interface aggregated header file │ ├── es_add.h ... # Single operator header file (generally multiple files) │ ├── es_add.cpp ... # Single operator implementation file (generally multiple files) │ └── es_math_all_in_one.cpp # Aggregated wrapper ├── python_package/ │ └── dist/ │ └── es_math-1.0.0-py3-none-any.whl # Python package ├── libes_math.so # Dynamic library (CMake default library output directory) └── libes_math.a # Static libraryExample 6: Multiple TARGETs# Generate math TARGET add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output ) # Generate nn TARGET add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_nn OPP_PROTO_TARGET opgraph_nn OUTPUT_PATH ${CMAKE_BINARY_DIR}/output ) # Use multiple TARGETs add_executable(my_inference_app main.cpp) target_link_libraries(my_inference_app PRIVATE es_math es_nn )Example 7: Use in C Code#include es_math/es_math_ops.h #include ge/es/graph_builder.h using namespace ge::es; int main() { EsGraphBuilder builder(my_graph); // Create inputs auto input1 builder.CreateConstFloat(1.0f); auto input2 builder.CreateConstFloat(2.0f); // Use generated ES API auto result Add(input1, input2); auto graph builder.build_and_reset(); return 0; }Example 8: Use in Python# Install wheel package pip install output/whl/es_math-1.0.0-py3-none-any.whl# Plugins auto-loaded via entry_point mechanism, use unified import method from ge.es.math import Add from ge.es import GraphBuilder builder GraphBuilder(my_graph) input1 builder.create_const_float(1.0) input2 builder.create_const_float(2.0) result Add(input1, input2) graph builder.build_and_reset()Note:Plugins auto-loaded via entry_point mechanism, import path isge.es.module_namemodule_nameis derived by removinges_prefix fromES_LINKABLE_AND_ALL_TARGET(likees_math→math)Can usege.es.list_plugins()to view all loaded plugin namesCan usege.es.get_plugin(math)to check if plugin exists (returns module object or None).Example 9: Historical Prototype Library Generation Mode (Commercial Release First Build, Archive Current Version Prototype)# Extract IR prototype from installed operator prototype .so, archive as JSON for next commercial release use set(GE_ES_EXTRACT_HISTORY ON) set(GE_ES_RELEASE_VERSION 8.0.RC1) set(GE_ES_RELEASE_DATE 2026-02-28) # Optional, if not set uses current date set(GE_ES_BRANCH_NAME release/8.0) # Optional; if set to master wont execute archive, only code generation add_es_library( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output ) # Artifacts: output/index.json, output/registry/8.0.RC1/metadata.json, output/registry/8.0.RC1/operators.jsonExample 10: Code Generation Mode with Historical Compatibility (Auto-consume Existing Historical Data, Generate C API with Overloads)# Function internally auto-detects ${CANN_INSTALL_PATH}/cann/opp/history_registry/math, # when path exists and is non-empty, auto-generates C interfaces with historical compatible overload signatures, no need to manually set path set(GE_ES_RELEASE_VERSION 8.0.RC2) add_es_library( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output ) # Generated header files have multi-version overloads for same operator (old signature new signature), forward compatible with old version callsExample 11: Complete Commercial Release Mode (Single Call, Function Internally Auto-completes Code Generation Historical Prototype Library ArchiveMerge)# GE_ES_EXTRACT_HISTORYON ops package contains historical prototype library (auto-detected) complete commercial release mode # add_es_library internally auto executes gen_esb twice in sequence, caller doesnt need extra handling: # gen_esb call 1: default codegen mode, auto-selects historical versions within window anchored at current date → compares current prototype → generates C API with overloads # gen_esb call 2: --es_modeextract_history, copies existing historical library from _AUTO_HISTORY_REGISTRY to OUTPUT_PATH, appends current version prototype in OUTPUT_PATH → OUTPUT_PATH contains complete historical prototype library set(GE_ES_EXTRACT_HISTORY ON) set(GE_ES_RELEASE_VERSION 8.0.RC2) # Current new version number, for archive step set(GE_ES_RELEASE_DATE 2026-02-28) # Optional set(GE_ES_BRANCH_NAME develop) # Optional; if set to master wont archive, only code generation add_es_library( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output )Naming RulesArtifact NamingArtifact TypeNaming RuleExample (ES_LINKABLE_AND_ALL_TARGETes_math)Dynamic LibrarylibES_LINKABLE_AND_ALL_TARGET.solibes_math.soStatic LibrarylibES_LINKABLE_AND_ALL_TARGET.alibes_math.aPython PackageES_LINKABLE_AND_ALL_TARGET-1.0.0-py3-none-any.whles_math-1.0.0-py3-none-any.whlAggregated Header Filees_name_ops.hes_math_ops.hTarget NamingTarget TypeNaming RuleExample (ES_LINKABLE_AND_ALL_TARGETes_math)External LibraryES_LINKABLE_AND_ALL_TARGETes_mathNotesES_LINKABLE_AND_ALL_TARGET Naming:Recommend usinges_prefix (likees_math,es_nn)Use lowercase letters and underscoresAvoid special characters and C keywordsHistorical Prototype Library Related Variables:Historical prototype library path isauto-derivedby function (${CANN_INSTALL_PATH}/cann/opp/history_registry/module), when path exists and is non-empty auto-enables, caller doesnt need to pass parametersmaster branch: WhenGE_ES_BRANCH_NAMEismaster, will ignoreGE_ES_EXTRACT_HISTORY/GE_ES_RELEASE_VERSION/GE_ES_RELEASE_DATE, only run pure code generation mode (historical prototype library path still passed, for generating C API with overloads)GE_ES_EXTRACT_HISTORYONand ops package contains historical prototype library (auto-detected) iscomplete commercial release mode, function internally auto executes gen_esb twice (code generation historical prototype library archivemerge), caller doesnt need any extra handling (see Example 11)Version Deduplication: If historical prototype librarysindex.jsonalready contains same version number asGE_ES_RELEASE_VERSION, skips archive step, only executes code generation (avoid duplicate archiving); simultaneously copies complete historical prototype library from CANN installation path toOUTPUT_PATH, convenient for subsequent path change installationPure historical archive mode (only setGE_ES_EXTRACT_HISTORYON, ops package has no historical prototype library): gen_esb outputs toOUTPUT_PATH, only generates JSON, no C APIIn complete commercial release mode, code generation step gen_esb doesnt pass--release_version, auto-selects historical versions within window anchored at current date for comparison; archive step usesGE_ES_RELEASE_VERSIONas new version number to write into historical libraryIn complete commercial release mode, archive step copies existing historical library from_AUTO_HISTORY_REGISTRY(CANN installation path, read-only) toOUTPUT_PATH(build directory, writable), gen_esb appends current version entry inOUTPUT_PATH; first build (no existing historical library in CANN path) directly outputs toOUTPUT_PATH; finalOUTPUT_PATHcontains complete merged result of all historical versions current versionGE_ES_RELEASE_VERSIONmust be set during archiving, otherwise archived version cannot be identifiedHistorical prototype library data (JSON files) usually installed with ops package, default location${CANN_INSTALL_PATH}/cann/opp/history_registry/package_name/Dependency RequirementsCMake Version: 3.16CANN run Package: Installed and environment variables set (or manually specify path)gen_esb: This is internal es api code generation binary tool, integrated in run package, can view usage viagen_esb --helpOPP_PROTO_TARGET: Must existPython3: 3.7 (only needed foradd_es_library_and_whl)Python Packages: setuptools, wheel (only needed foradd_es_library_and_whl), recommend using setuptools59.6.0、wheel0.37.1 compatible version or higher versionCommon QuestionsQ: How can multiple TARGETs share output directory?A: All TARGETs can use sameOUTPUT_PATH, header files will be organized in subdirectories by package name:add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output # Shared path ) add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_nn OPP_PROTO_TARGET opgraph_nn OUTPUT_PATH ${CMAKE_BINARY_DIR}/output # Shared path ) # Output structure: # output/ # ├── include/ # │ ├── es_math/ # │ └── es_nn/ # ├── lib64/ # │ ├── libes_math.so, libes_math.a # │ └── libes_nn.so, libes_nn.a # └── whl/ # ├── es_math-1.0.0-py3-none-any.whl # └── es_nn-1.0.0-py3-none-any.whlQ: What if gen_esb cannot be found?A: Function will automatically search for gen_esb, if fails please check:Confirm CANN run package is installedExecutesource ${ASCEND_HOME_PATH}/set_env.shor set correct CMAKE_MODULE_PATHgen_esb will auto-derive from PATH environment variable or cmake file pathFunction will output detailed detection information, troubleshoot based on logs.Complete Example# Basic Settings cmake_minimum_required(VERSION 3.16) project(my_es_project LANGUAGES CXX) # Import Functions (Recommended: use find_package) list(APPEND CMAKE_MODULE_PATH ${ASCEND_HOME_PATH}/include/ge/cmake) find_package(GenerateEsPackage REQUIRED) # Part 1: Prerequisites - Define Prototype Library add_library(opgraph_math SHARED ) # Part 2: Generate ES API Package add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output ) # Part 3: Use in Application add_executable(my_app src/main.cpp src/inference.cpp ) # Link ES_LINKABLE_AND_ALL_TARGET target_link_libraries(my_app PRIVATE es_math # Auto get dependencies, headers and library )Build Command:# Just one command! make my_app【免费下载链接】geGEGraph Engine是面向昇腾的图编译器和执行器提供了计算图优化、多流并行、内存复用和模型下沉等技术手段加速模型执行效率减少模型内存占用。 GE 提供对 PyTorch、TensorFlow 前端的友好接入能力并同时支持 onnx、pb 等主流模型格式的解析与编译。项目地址: https://gitcode.com/cann/ge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考