!19028 优化Native API的介绍文档

Merge pull request !19028 from hhj/ndk_doc

zh-cn/application-dev/napi/introduction.md → zh-cn/application-dev/reference/native-api-intro.md

-# Native API介绍
-
-Native API是OHOS SDK上提供的一组native开发接口与工具集合，方便开发者使用C或者C++语言实现应用的关键功能。Native API只覆盖了OHOS基础的一些底层能力，如libc，图形库，窗口系统，多媒体，压缩库等，并没有完全提供类似于JS API上的完整的OHOS 平台能力。在应用中使用Native API会编译成动态库打包到应用中。
-
-## Native API构成介绍
-
-### Native API目录结构
-
-Native API在SDK包的位置为$(SDK_ROOT)/native目录，主要有以下几个部分组成
-
-|目录|功能说明|
-|--|--|
-|build|应用中编译动态库的toolchain cmake脚本；这个目录下ohos.toolchain.cmake文件定义了给OHOS交叉编译选项|
-|build-tools|放置编译构建的工具，如cmake|
-|docs|Native API接口参考文档，通过doxgen从头文件中提取出来|
-|llvm|支持OHOS ABI的llvm交叉编译器|
-|sysroot|放置编译链接的依赖文件目录，包含头文件，动态库等|
-
-### Native API接口
-
-|接口分类|接口功能|引入版本|
-|--|--|--|
-|标准C库|以musl为基础提供的标准c库接口，当前提供了1500+的接口|8|
-|标准C++库|c++运行时库libc++_shared，此库在打包的时候需要打包或者静态链接到应用中|8|
-|日志|打印日志到系统的hilog接口|8|
-|napi|ArkUI提供的，方便应用开发接入JS应用环境的一组类Node-API，是属于Native API的一部分|8|
-|XComponent|ArkUI XComponent组件中的surface与触屏事件接口，方便开发者开发高性能图形应用|8|
-|libuv|ArkUI集成的三方的异步IO库|8|
-|libz|zlib库，提供基本的压缩，解压接口|8|
-|Drawing|系统提供的2D图形库，可以在surface进行绘制|8|
-|OpenGL|系统提供的openglv3接口|8|
-|Rawfile|应用资源访问接口，可以读取应用中打包的各种资源|8|
-|OpenSLES|用于2D，3D音频加速的接口库|8|
-|Mindspore|AI模型接口库|9|
-|包管理|包服务接口，方便查询应用包信息|8|
-
-Native API中有一部分接口采用开源标准，详细列表见《[Native API中支持的标准库](../reference/native-lib/third_party_libc/musl.md)》《[Node_API](../reference/native-lib/third_party_napi/napi.md)》
-
-## 使用介绍
-
-### 建议使用Native API的场景
-
-主要有如下一些
-
-1. 应用性能敏感代码，比如游戏，物理模拟等计算密集型场景
-2. 需要复用已有的C或C++库
-3. 需要针对CPU特性进行专项定制的库，如neon加速
-
-### 不建议使用Native API的场景
-
-1. 写一个纯native的的OHOS应用
-2. 希望在尽可能多的OHOS设备上保持兼容的应用
+# Native API（NDK）入门
+
+Native API是OpenHarmony SDK上提供的一组native开发接口与工具集合（也称为NDK），方便开发者使用C或者C++语言实现应用的关键功能。Native API只覆盖了OHOS基础的一些底层能力，如libc，图形库，窗口系统，多媒体，压缩库等，并没有完全提供类似于JS API上的完整的OHOS 平台能力。在应用中使用Native API会编译成动态库打包到应用中。
+
+## 名词概念
+|名词|名词解释|
+|--|--|
+|Native API|OHOS SDK里面native包提供的，面向三方应用开发的Native 接口以及相应编译脚本，编译工具链。包括C运行时基础库libc，3D图形库opengl，面向JS与C跨语言的接口Node-API等，具体内容详见下表。|
+|NDK|Native Develop Kit的缩写，在OHOS上就是Native API；Native API是官方名字，NDK指代相同意思。|
+|SDK CAPI|OHOS Native API中的C语言接口，以及工具链部分，当前OHOS的Native API里面只包含C语言接口，因此Native API与CAPI意思一样，建议交流的时候使用CAPI，防止Native API与napi缩写混用。|
+|Node-API|曾用名napi，是OHOS中提供JS与C跨语言调用的接口，是Native API接口中的一部分. 该接口在Node.js提供的Node-API基础上扩展而来，但不完全与Node.js中的Node-API完全兼容。 |
+|napi|Node-API的曾用名，当前Node-API头文件中的接口仍然以napi_开头，不建议使用。|
+## Native API构成介绍
+
+### Native API目录结构
+
+Native API在SDK包的位置为$(SDK_ROOT)/native目录，主要有以下几个部分组成
+
+|目录|功能说明|
+|--|--|
+|build|应用中编译动态库的toolchain cmake脚本；这个目录下ohos.toolchain.cmake文件定义了给OHOS交叉编译选项|
+|build-tools|放置编译构建的工具，如cmake|
+|docs|Native API接口参考文档，通过doxgen从头文件中提取出来|
+|llvm|支持OHOS ABI的llvm交叉编译器|
+|sysroot|放置编译链接的依赖文件目录，包含头文件，动态库等|
+
+### Native API接口
+
+|接口分类|接口功能|引入版本|
+|--|--|--|
+|[标准C库](native-lib/third_party_libc/musl.md)|以musl为基础提供的标准c库接口，当前提供了1500+的接口|8|
+|[标准C++库](native-lib/third_party_libc/cpp.md)|c++运行时库libc++_shared，此库在打包的时候需要打包或者静态链接到应用中|8|
+|日志|打印日志到系统的hilog接口|8|
+|Node-API|ArkUI提供的，方便应用开发接入JS应用环境的一组类Node-API（也叫napi），是属于Native API的一部分|8|
+|XComponent|ArkUI XComponent组件中的surface与触屏事件接口，方便开发者开发高性能图形应用|8|
+|libuv|ArkUI集成的三方的异步IO库|8|
+|libz|zlib库，提供基本的压缩，解压接口|8|
+|Drawing|系统提供的2D图形库，可以在surface进行绘制|8|
+|OpenGL|系统提供的openglv3接口|8|
+|Rawfile|应用资源访问接口，可以读取应用中打包的各种资源|8|
+|OpenSLES|用于2D，3D音频加速的接口库|8|
+|Mindspore|AI模型接口库|9|
+|包管理|包服务接口，方便查询应用包信息|8|
+
+
+### Native API相关资料
+* 《[Native API参考手册](./native-apis/Readme-CN.md)》，介绍各个API参考手册
+* 《[Native API中支持的标准库](../reference/native-lib/Readme-CN.md)》，介绍Native API支持的开源标准库
+* 《[Native API开发指南](../napi/Readme-CN.md)》，结合具体的例子，场景介绍各类接口的使用
+* 《[使用NDK编译一个Cmake C/C++工程文档](../quick-start/howto-migrate-cmake-with-ohosndk.md)》，介绍如何使用使用Native API开发一个Cmake工程
+* 《[Node-API在应用工程中的使用指导](../napi/napi-guidelines.md)》, 如何使用Node-API接口
+
+
+## 使用建议
+
+### 建议使用Native API的场景
+
+主要有如下一些
+
+1. 应用性能敏感代码，比如游戏，物理模拟等计算密集型场景
+2. 需要复用已有的C或C++库
+3. 需要针对CPU特性进行专项定制的库，如neon加速
+
+### 不建议使用Native API的场景
+
+1. 写一个纯native的的OHOS应用
+2. 希望在尽可能多的OHOS设备上保持兼容的应用
+
+## 维测能力
+
+1. OHOS官方提供lldb remote方式代码调试，详细参看《[lldb参考手册](https://gitee.com/openharmony/third_party_llvm-project/blob/master/lldb/README_zh.md)》
+2. musl库的log维测能力，请参看[libc库](./native-lib/third_party_libc/musl.md)维测章节

zh-cn/application-dev/reference/native-lib/Readme-CN.md

 # Native API标准库
+- [libc标准库](third_party_libc/musl.md)
+- [c++标准库](third_party_libc/cpp.md)
 - [Node-API](third_party_napi/napi.md)
 - [libuv](third_party_libuv/libuv.md)
-- [Native API中支持的标准库](third_party_libc/musl.md)
+- [OpenSL ES](third_party_opensles/opensles.md)
+- [OpenGL ES](third_party_opengl/opengles.md)
+- [EGL](third_party_opengl/egl.md)
+- [Zlib](third_party_zlib/zlib.md)
 - 附录
-  - [Native api中没有导出的符号列表](third_party_libc/musl-peculiar-symbol.md)
-  - [Native api中由于权限管控可能调用失败的符号列表](third_party_libc/musl-permission-control-symbol.md)
+  - [libc中没有导出的符号列表](third_party_libc/musl-peculiar-symbol.md)
+  - [libc中由于权限管控可能调用失败的符号列表](third_party_libc/musl-permission-control-symbol.md)
   - [Native api中导出的EGL符号列表](third_party_opengl/egl-symbol.md)
   - [Native api中导出的OpenGL ES 3.0符号列表](third_party_opengl/openglesv3-symbol.md)
   - [Native api中支持的OpenSL ES接口列表](third_party_opensles/opensles.md)
\ No newline at end of file

zh-cn/application-dev/reference/native-lib/third_party_libc/cpp.md

+
+# 标准C++库
+
+OpenHarmony当前使用的是llvm项目的C++标准库实现[libc++](https://libcxx.llvm.org/)。
+
+## 版本
+
+从OpenHarmony 3.0开始，libc++使用clang/llvm 10.0.1版本
+
+从OpenHarmony 3.2开始，libc++升级到clang/llvm 12.0.1版本
+
+从OpenHarmony 4.0开始，libc++升级到clang/llvm 15.0.4版本
+
+## 支持的能力
+
+C++11、C++14标准已完全支持，C++17和C++20标准正在完善。具体语言特性支持标准可以参考[https://libcxx.llvm.org/](https://libcxx.llvm.org/)网站对应的ReleaseNotes。
+
+## ABI(application binary interface)兼容
+在OpenHarmony系统中，系统库与应用Native库都在使用C++标准库，两部分依赖的版本是不一样的。系统库依赖的C++标准库随镜像版本升级，而应用Native库依赖的C++标准库随编译使用的SDK版本升级，两部分依赖的C++基础库会跨多个大版本，产生ABI兼容性问题。为了解决此问题，OpenHarmony上把两部分依赖的C++标准库进行了区分。
+  * 系统库：使用libc++.so， 随系统镜像发布
+  * 应用Native库：使用libc++_shared.so，随应用发布
+
+两个库使用的C++命名空间不一样，libc++_shared.so使用__n1作为C++符号的命名空间，libc++.so使用__h作为C++符号的命名空间。
+
+注意：两边使用的C++标准库不能进行混用，Native API接口当前只能是C接口，可以通过这个接口隔离两边的C++运行环境。
\ No newline at end of file

zh-cn/application-dev/reference/native-lib/third_party_libc/musl-permission-control-symbol.md

-# Native api中由于权限管控可能调用失败的符号列表
+# Native API中由于权限管控可能调用失败的符号列表
+
+使用如下接口请确保应用实体有相应的权限。
 
 | 符号名 | 调用失败可能的原因 |
 | --- | --- |

zh-cn/application-dev/reference/native-lib/third_party_libc/musl.md

-# Native API中支持的标准库
-
-## 简介
-
-**表1** OpenHarmony支持的标准库
-
-| 名称      | 简介                                                         |
-| :-------- | :----------------------------------------------------------- |
-| 标准C库   | [libc、libm、libdl](https://zh.cppreference.com/w/c/header)组合实现C11标准C库。      |
-| 标准C++库 | [libc++](https://libcxx.llvm.org/) 是C++标准库的一种实现。   |
-| OpenSL ES | [OpenSL ES](https://www.khronos.org/registry/OpenSL-ES/)是一个嵌入式跨平台的音频处理库。 |
-| zlib      | [Zlib](https://zlib.net/)是基于C/C++语言实现的一个通用的数据压缩库。 |
-| EGL   | [EGL](https://www.khronos.org/egl/)是渲染API与底层原生窗口系统之间的一种标准的软件接口。 |
-| OpenGL ES | [OpenGL ES](https://www.khronos.org/opengles/)是一个嵌入式跨平台的为 3D 图形处理硬件指定标准的软件接口。 |
-
-## 标准C库
-
-[libc、libm、libdl](https://zh.cppreference.com/w/c/header)组合实现C11标准C库。
-
-libc：包含线程相关接口，以及大部分标准接口。
-
-libm：数学库函数接口。
-
-libdl：dlopen等动态链接器接口。
-
-**版本**
-
-1.2.0
-
-**支持的能力**
-
-C标准函数库是在C语言程序设计中，所有符合标准的头文件的集合，以及常用的函数库实现程序（如I/O输入输出和字符串控制）。
-
-**musl**
-
-[native api中没有导出的符号列表](musl-peculiar-symbol.md)
-
-[native api由于权限管控可能调用失败的符号列表](musl-permission-control-symbol.md)
-
-## 标准C++库
-
-[libc++](https://libcxx.llvm.org/)是C++标准库的一种实现。
-
-**版本**
-
-10.0.1
-
-**支持的能力**
-
-C++11、C++14标准已完全支持，C++17和C++20标准正在完善。
-
-## OpenSL ES
-
-[OpenSL ES](https://www.khronos.org/registry/OpenSL-ES/)是一个嵌入式跨平台的音频处理库。
-
-**支持的能力**
-
-[Native api中支持的OpenSL ES接口列表](../third_party_opensles/opensles.md)
-
-## zlib
-
-[Zlib](https://zlib.net/)是基于C/C++语言实现的一个通用的数据压缩库。
-
-## EGL
-
-EGL 是Khronos渲染API (如OpenGL ES 或 OpenVG) 与底层原生窗口系统之间的接口。OpenHarmony 现已支持 EGL。
-
-**标准库中导出的符号列表**
-
-[native api中导出的EGL符号列表](../third_party_opengl/egl-symbol.md)
-
-## OpenGL ES
-
-OpenGL 是一种跨平台的图形 API，用于为 3D 图形处理硬件指定标准的软件接口。[OpenGL ES](https://www.khronos.org/opengles/) 是 OpenGL 规范的一种形式，适用于嵌入式设备。OpenHarmony 现已支持 OpenGL ES 3.0。
-
-**支持的能力**
-
-OpenGL ES 3.0
-
-**标准库中导出的符号列表**
-
-[native api中导出的OpenGL ES 3.0符号列表](../third_party_opengl/openglesv3-symbol.md)
-
+# libc标准库
+
+## 简介
+C标准函数库在C语言程序设计中，提供符合标准的头文件，以及常用的库函数实现（如I/O输入输出和字符串控制）。
+
+OpenHarmony采用musl作为C标准库，musl库是一个轻量，快速，简单，免费的开源libc库，详细介绍参考[musl官方参考手册](http://musl.libc.org/manual.html)。
+
+musl与glibc的差异点请参考[musl与glibc功能对比](https://wiki.musl-libc.org/functional-differences-from-glibc.html)。
+
+## 标准C库组件介绍
+
+[libc、libm、libdl](https://zh.cppreference.com/w/c/header)组合实现C11标准C库。
+
+libc：包含线程相关接口，以及大部分标准接口。
+
+libm：数学库函数接口，当前在OpenHarmony中是一个链接，实际都在libc中定义。
+
+libdl：dlopen等动态链接器接口，当前在OpenHarmony中是一个链接，实际都在libc中定义。
+
+## musl版本号
+
+1.2.0
+
+从OpenHarmony4.0开始，版本升级到1.2.3
+
+## 支持的能力
+提供兼容C99,C11,POSIX标准的头文件，以及库函数接口，但不是完全兼容；支持armv7a，arm64, x86_64三种架构的支持；
+
+为了更好的适配OpenHarmony设备的高性能，低内存，高安全，轻量化，支持多种形态设备的基本特征；在musl开源库的基础上进行了优化，增强，对不适用嵌入式设备的接口进行了裁剪。
+
+### 新增能力
+1. 动态加载器支持命名空间隔离能力，应用可以dlopen加载的动态库受系统命名空间限制（比如，无法打开系统侧动态库）。
+2. 支持dlclose真实卸载动态库能力，musl的开源版本不支持。
+3. 支持symbol-versioning功能。
+4. dlopen支持直接加载zip包中未压缩的文件。
+
+### 调试能力
+提供了基础的log调试能力，方便开发者需要查看libc库内部异常。维测log的提供动态开关功能，不需要重新编译。在正式发布版本中，不建议使用，会影响运行性能。
+
+#### 1. musl.log功能
+设置musl.log.enable属性为true，打开musl的log打印。打印其他日志，需要先打开此开关。
+```
+setparam musl.log.enable true
+```
+
+#### 2. 加载器log功能
+调试程序引导，dlopen，dlclose等加载器接口，需要打开加载器log。用法如下：
+* 使能全部应用的加载器log，谨慎使用
+```
+setparam musl.log.ld.app true
+```
+* 使能指定应用的加载器log，{app_name}需要替换成真实需要打印log的应用名字
+```
+setparam musl.log.ld.all false
+setparam musl.log.ld.app.{app_name} true
+```
+* 打印全部应用除指定名字应用外的加载器日志
+```
+setparam musl.log.ld.all true
+setparam musl.log.ld.app.{app_name} false
+```
+
+## musl不支持接口列表
+[native api中没有导出的符号列表](musl-peculiar-symbol.md)
+[native api由于权限管控可能调用失败的符号列表](musl-permission-control-symbol.md)
+
+
 <!--no_check-->
\ No newline at end of file

zh-cn/application-dev/reference/native-lib/third_party_opengl/egl.md

+
+# EGL
+
+EGL 是Khronos渲染API (如OpenGL ES 或 OpenVG) 与底层原生窗口系统之间的接口。OpenHarmony 现已支持 EGL。
+
+## 标准库中导出的符号列表
+
+[native api中导出的EGL符号列表](egl-symbol.md)
+

zh-cn/application-dev/reference/native-lib/third_party_opengl/opengles.md

+# OpenGL ES
+
+OpenGL 是一种跨平台的图形 API，用于为 3D 图形处理硬件指定标准的软件接口。[OpenGL ES](https://www.khronos.org/opengles/) 是 OpenGL 规范的一种形式，适用于嵌入式设备。OpenHarmony 现已支持 OpenGL ES 3.0。
+
+## 支持的能力
+
+OpenGL ES 3.0
+
+## 标准库中导出的符号列表
+
+[native api中导出的OpenGL ES 3.0符号列表](openglesv3-symbol.md)
\ No newline at end of file

zh-cn/application-dev/reference/native-lib/third_party_zlib/zlib.md

+# zlib
+
+[Zlib](https://zlib.net/)是基于C/C++语言实现的一个通用的数据压缩库。
\ No newline at end of file