From 4fd844a77788a229c5021602316e0b8496e39f3c Mon Sep 17 00:00:00 2001 From: zhangchen Date: Mon, 25 Dec 2023 03:35:18 +0000 Subject: [PATCH] Update the README for compact and system api Issue: https://gitee.com/openharmony/arkcompiler_ets_frontend/issues/I8R0ND Signed-off-by: zhangchen Change-Id: Ica0f57d365c17a92f0190240b872339b8489d904 --- arkguard/README-cn.md | 26 +++++++++++++++++++------- arkguard/README.md | 29 ++++++++++++++++++++--------- 2 files changed, 39 insertions(+), 16 deletions(-) diff --git a/arkguard/README-cn.md b/arkguard/README-cn.md index 9f980d5165..94703c47ac 100644 --- a/arkguard/README-cn.md +++ b/arkguard/README-cn.md @@ -101,7 +101,7 @@ Arkguard只混淆参数名和局部变量名(通过将它们重新命名为随 } ``` * 被[保留选项](#保留选项)指定的属性名不会被混淆。 -* 系统API列表中的属性名不会被混淆。系统API列表是构建时从SDK中自动提取出来的一个名称列表。 +* 系统API列表中的属性名不会被混淆。系统API列表是构建时从SDK中自动提取出来的一个名称列表，其缓存文件为systemApiCache.json，路径为工程目录下build/cache/{...}/release/obfuscation中 * 在Native API场景中，在so的d.ts文件中声明的API不会被混淆。 * 字符串字面量属性名不会被混淆。比如下面例子中的`"name"`和`"age"`不会被混淆。 ``` @@ -113,7 +113,18 @@ Arkguard只混淆参数名和局部变量名(通过将它们重新命名为随 -enable-property-obfuscation -enable-string-property-obfuscation ``` - 注意：如果你的代码里面有字符串属性名包含特殊字符(除了`a-z, A-Z, 0-9, _`之外的字符)，比如`let obj = {"\n": 123, "": 4, " ": 5}`，我们建议不要开启`-enable-string-property-obfuscation`选项，因为当你不想混淆这些名字时，可能无法通过[保留选项](#保留选项)来指定保留这些名字。 + **注意**： + **1.** 如果代码里面有字符串属性名包含特殊字符(除了`a-z, A-Z, 0-9, _`之外的字符)，比如`let obj = {"\n": 123, "": 4, " ": 5}`，建议不要开启`-enable-string-property-obfuscation`选项，因为当不想混淆这些名字时，可能无法通过[保留选项](#保留选项)来指定保留这些名字。 + **2.** 系统API的属性白名单中不包含声明文件中使用的字符串常量值，比如示例中的字符串'ohos.want.action.home'不被包含在属性白名单中 + ``` + // 系统API文件@ohos.app.ability.wantConstant片段： + export enum Params { + ACTION_HOME = 'ohos.want.action.home' + } + // 开发者源码示例： + let params = obj['ohos.want.action.home']; + ``` + 因此在开启了`-enable-string-property-obfuscation`选项时，如果想保留代码中使用的系统API字符串常量的属性不被混淆，比如obj['ohos.want.action.home'], 那么需要使用keep选项保留。 `-enable-toplevel-obfuscation` @@ -134,7 +145,8 @@ Arkguard只混淆参数名和局部变量名(通过将它们重新命名为随 `-compact` -去除不必要的空格符和所有的换行符。如果你使用这个选项，那么所有代码会被压缩到一行。 +去除不必要的空格符和所有的换行符。如果使用这个选项，那么所有代码会被压缩到一行。 +**注意**：release模式构建的应用栈信息仅包含代码行号，不包含列号，因此compact功能开启后无法依据报错栈中的行号定位到源码具体位置。 `-remove-log` @@ -142,16 +154,16 @@ Arkguard只混淆参数名和局部变量名(通过将它们重新命名为随 `-print-namecache` filepath -将名称缓存保存到指定的文件路径。名称缓存包含名称混淆前后的映射。如果你使用了`-enable-property-obfuscation`或 -`-enable-toplevel-obfuscation`选项，并且你希望未来进行增量编译(比如热修复)，那么你应该使用这个选项， -并且将缓存文件保管好。 +将名称缓存保存到指定的文件路径。名称缓存包含名称混淆前后的映射。 +注意：每次全量构建工程时都会生成新的namecache.json文件，因此您每次发布新版本时都要注意保存一个该文件的副本。 `-apply-namecache` filepath 复用指定的名称缓存文件。名字将会被混淆成缓存映射对应的名字，如果没有对应，将会被混淆成新的随机段名字。 该选项应该在增量编译场景中被使用。 -默认情况下，DevEco Studio会在临时的缓存目录中保存缓存文件，并且在增量编译场景中自动应用该缓存文件。 +默认情况下，DevEco Studio会在临时的缓存目录中保存缓存文件，并且在增量编译场景中自动应用该缓存文件。 +缓存目录：build/cache/{...}/release/obfuscation ### 保留选项 diff --git a/arkguard/README.md b/arkguard/README.md index 19982b59f0..42605e527d 100644 --- a/arkguard/README.md +++ b/arkguard/README.md @@ -114,7 +114,7 @@ their property names, you need to use [keep options](#keep-options) to keep them ``` will not be obfuscated. * the property names that are specified by [keep options](#keep-options). -* the property names in system API list. System API list is a name set which is extracted from SDK automatically by default. +* the property names in system API list. System API list is a name set which is extracted from SDK automatically by default. The cache file is systemApiCache.json, and the path is build/cache/{...}/release/obfuscation in the module directory. * in the Native API scenario, the APIs in the d.ts file of so library will not be obfuscated. * the property names that are string literals. For example, the property names "name" and "age" in the following code will not be obfuscated. ``` @@ -126,10 +126,21 @@ their property names, you need to use [keep options](#keep-options) to keep them -enable-property-obfuscation -enable-string-property-obfuscation ``` - Note: If there are string literal property names which contain special characters (that is, all characters except + **Note**: + **1.** If there are string literal property names which contain special characters (that is, all characters except `a-z, A-Z, 0-9, _`, for example `let obj = {"\n": 123, "": 4, " ": 5}` then we would not suggest to enable the option `-enable-string-property-obfuscation`, because [keep options](#keep-options) may not allow to keep these - names when you do not want to obfuscate them. + names when you do not want to obfuscate them. + **2.** The property white list of the system API does not include the string constant in the declaration file. For example, the string `'ohos.want.action.home'` in the example is not included in the white list. + ``` + // System Api @ohos.app.ability.wantConstant snippet: + export enum Params { + DLP_PARAM_SANDBOX = 'ohos.dlp.param.sandbox' + } + // Developer source example： + let params = obj['ohos.want.action.home']; + ``` + Therefore, when `-enable-string-property-obfuscation` is enabled, if you don't want to obfuscate the property like `'ohos.dlp.param.sandbox'`, which is a string constant in system api. you should keep it manually. Specifies to obfuscate the names in the global scope. If you use this option, all global names will be obfuscated except the following: @@ -150,7 +161,8 @@ Specifies to obfuscate the file/folder names. This option only takes effect in O `-compact` Specifies to remove unnecessary blank spaces and all line feeds. If you use this option, all code will be compressed into -one line. +one line. +**Note**: The stack information in release mode only includes the line number of code, not the column number. Therefore, when the compact is enabled, the specific location of the source code cannot be located based on the line number of stack information. `-remove-log` @@ -158,10 +170,8 @@ Specifies to remove all `console.*` statements. `-print-namecache` filepath -Specifies to print the name cache that contains the mapping from the old names to new names. The cache will printed to -the given file. If you use `-enable-property-obfuscation` or `-enable-toplevel-obfuscation`, and you want incremental -obfuscation in the future (for example, hot fix), then you should use this option and keep the resulting cache file -carefully. +Specifies to print the name cache that contains the mapping from the old names to new names. +Note: The namecache.json file will be generated every time the module is fully built, so you should save a copy each time you publish a new version. `-apply-namecache` filepath @@ -169,7 +179,8 @@ Specifies to reuse the given cache file. The old names in the cache will receive the cache. Other names will receive new random short names. This option should be used in incremental obfuscation. By default, DevEco Studio will keep and update the namecache file in the temporary cache directory and apply the cache for -incremental compilation. +incremental compilation. +Cache directory: build/cache/{...}/release/obfuscation ### Keep options -- Gitee