002fbd5c创建于 2025年1月23日历史提交

app.json5 Configuration File

Configuration File Example

This topic gives an overview of the app.json5 configuration file. To start with, let's go through an example of what this file contains.

{
  "app": {
    "bundleName": "com.application.myapplication",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:layered-image",
    "label": "$string:app_name",
    "description": "$string:description_application",
    "minAPIVersion": 9,
    "targetAPIVersion": 9,
    "apiReleaseType": "Release",
    "debug": false,
    "car": {
      "minAPIVersion": 8
    },
    "targetBundleName": "com.application.test",
    "targetPriority": 50,
    "appEnvironments": [
      {
        "name":"name1",
        "value": "value1"
      }
    ],
    "maxChildProcess": 5,
    "multiAppMode": {
      "multiAppModeType": "multiInstance",
      "maxCount": 5
    },
    "hwasanEnabled": false,
    "ubsanEnabled": false,
    "cloudFileSyncEnabled": false,
    "configuration": "$profile:configuration"
  },
}

Tags in the Configuration File

As shown above, the app.json5 file contains several tags.

Table 1 Tags in the app.json5 file

Name	Description	Data Type	Initial Value Allowed
bundleName	Bundle name, which uniquely identifies an application. The value must comply with the following rules: - The bundle name contains at least three segments, separated by periods (.). Each segment can contain only letters, digits, and underscores (_). - The first segment starts with a letter, and other segments start with a digit or letter. Each segment ends with a digit or letter. - Consecutive periods (.) are not allowed. - Contains 7 to 128 bytes. You are advised to use the reverse domain name notation, for example, com.example.demo, where the first part is the domain suffix com, the second part is the vendor/individual name, and the third part is the application name, which can be of multiple levels. If an application is built with the system source code, you are advised to name it in com.ohos.demo notation, where ohos signifies that the application is a system application.	String	No
bundleType	Bundle type, which is used to distinguish applications and atomic services. The options are as follows: - app: The bundle is an application. - atomicService: The bundle is an atomic service. - shared: The bundle is a shared library. This option is reserved. - appService: The bundle is a system-level shared library and can be used only by system applications.	String	Yes (initial value: app)
debug	Whether the application can be debugged. - true: Can be debugged. Used in the development phase. - false: Cannot be debugged. Used in the release phase.	Boolean	Yes (initial value: false) This tag is generated by DevEco Studio during compilation and building.
icon	Icon of the application. The value is the index to an icon resource file.	String	No
label	Name of the application. The value is the index to a string resource. It is a string with a maximum of 63 bytes.	String	No
description	Description of the application. The value is the index to a description. It is a string with a maximum of 255 bytes.	String	Yes (initial value: left empty)
vendor	Vendor of the application. The value is a string with a maximum of 255 bytes.	String	Yes (initial value: left empty)
versionCode	Version code of the application. The value is a positive integer less than 2 to the power of 31. It is used only to determine whether a version is later than another version. A larger value indicates a later version. Ensure that a new version of the application uses a value greater than any of its predecessors.	Number	No
versionName	Version number of the application displayed to users. The value contains a maximum of 127 bytes and consists of only digits and dots. The four-part format A.B.C.D is recommended, wherein: Part 1 (A): major version number, which ranges from 0 to 99. A major version consists of major new features or large changes. Part 2 (B): minor version number, which ranges from 0 to 99. A minor version consists of some new features or large bug fixes. Part 3 (C): feature version number, which ranges from 0 to 99. A feature version consists of scheduled new features. Part 4 (D): maintenance release number or patch number, which ranges from 0 to 999. A maintenance release or patch consists of resolution to security flaws or minor bugs.	String	No
minCompatibleVersionCode	Minimum compatible version of the application. It is used to check whether the application is compatible with a version on other devices in the cross-device scenario. The value ranges from 0 to 2147483647.	Number	Yes (initial value: value of versionCode)
minAPIVersion	Minimum API version required for running the application. The value ranges from 0 to 2147483647.	Number	Yes (initial value: value of compatibleSdkVersion in build-profile.json5)
targetAPIVersion	Target API version required for running the application. The value ranges from 0 to 2147483647.	Number	Yes (initial value: value of compileSdkVersion in build-profile.json5)
apiReleaseType	Type of the target API version required for running the application. The value can be "CanaryN", "BetaN", or "Release", where N represents a positive integer. - Canary: indicates a restricted release. - Beta: indicates a publicly released beta version. - Release: indicates a publicly released official version.	String	Yes (the value is automatically set by DevEco Studio based on the stage of the SDK in use; a manually set value will be overwritten during compilation and building)
accessible	Whether the installation directory of the application is accessible. This tag is effective only for system applications and pre-installed applications in the stage model.	Boolean	Yes (initial value: false)
multiProjects	Whether the application supports joint development of multiple projects. - true: The application supports joint development of multiple projects. For details about multi-project development, see Implementing Multi-Project Builds. - false: The application does not support joint development of multiple projects.	Boolean	Yes (initial value: false)
asanEnabled	Whether to enable AddressSanitizer (ASan) to detect memory corruption issues such as buffer overflows. - true: ASan is enabled. - false: ASan is disabled.	Boolean	Yes (initial value: false)
tablet	Tablet-specific configuration, which includes the minAPIVersion attribute. When running on tablets, the application applies the attribute settings under this tag and ignores the general settings in the app.json5 file.	Object	Yes (initial value: general settings in the app.json5 file)
tv	TV-specific configuration, which includes the minAPIVersion attribute. When running on TVs, the application applies the attribute settings under this tag and ignores the general settings in the app.json5 file.	Object	Yes (initial value: general settings in the app.json5 file)
wearable	Wearable-specific configuration, which includes the minAPIVersion attribute. When running on wearables, the application applies the attribute settings under this tag and ignores the general settings in the app.json5 file.	Object	Yes (initial value: general settings in the app.json5 file)
car	Telematics–specific configuration, which includes the minAPIVersion attribute. When running on telematics devices, the application applies the attribute settings under this tag and ignores the general settings in the app.json5 file.	Object	Yes (initial value: general settings in the app.json5 file)
default	Default device–specific configuration, which includes the minAPIVersion attribute. When running on default devices, the application applies the attribute settings under this tag and ignores the general settings in the app.json5 file.	Object	Yes (initial value: general settings in the app.json5 file)
targetBundleName	Target bundle name. The value rule and range are the same as those of bundleName. When a value is specified, the target application becomes one with the overlay feature.	String	Yes (initial value: left empty)
targetPriority	Priority of the application. The value ranges from 1 to 100. This tag can be configured only when targetBundleName is configured.	Number	Yes (initial value: 1)
generateBuildHash	Whether to generate hash values for all HAP and HSP files of the application by using the packaging tool. If this tag is set to true, the packaging tool generates hash values for all HAP and HSP files of the application. The hash values (if any) are used to determine whether the application needs to be updated when the system is updated in OTA mode but the versionCode value of the application remains unchanged. NOTE This tag applies only to system applications.	Boolean	Yes (initial value: false)
GWPAsanEnabled	Whether to enable GWP-ASan to detect memory safety errors, such as use-after-free and out-of-bounds memory read/write. - true: GWP-ASan is enabled. - false: GWP-ASan is disabled.	Boolean	Yes (initial value: false)
appEnvironments	Application environment variables configured for the current module.	Object array	Yes (initial value: left empty)
maxChildProcess	Maximum number of child processes that can be created by the current application. The value ranges from 0 to 512. The value 0 indicates that the number is not limited. If the application has multiple modules, use the configuration of the entry module.	Number	Yes (initial value: preconfigured value)
multiAppMode	Multi-app mode of the application. This tag takes effect only for the entry or feature module of the application whose bundleType is app. If there are multiple modules, use the configuration of the entry module.	Object	Yes (initial value: left empty)
hwasanEnabled	Whether HWAsan detection is enabled for an application. HardWare-assisted AddressSanitizer (HWAsan) is an enhanced Asan improved by the Top-Byte-Ignore feature. Compared with Asan, HWAsan has a lower memory overhead and a larger range of detection for memory errors. - true: HWAsan is enabled. - false: HWAsan is disabled.	Boolean	Yes (initial value: false)
ubsanEnabled	Whether UBsan detection is enabled for an application. Undefined Behavior Sanitizer (UBsan) is a tool used to detect undefined behavior in applications during runtime. It aims to help you detect potential errors and vulnerabilities in code. - true: UBsan is enabled. - false: UBsan is disabled.	Boolean	Yes (initial value: false)
cloudFileSyncEnabled	Whether device-cloud file synchronization is enabled for the application. - true: The device-cloud file synchronization is enabled. - false: The device-cloud file synchronization is disabled.	Boolean	Yes (initial value: false)
configuration	Whether the font size of the current application follows the system. This tag is a profile file resource that used to specify the configuration file that describes the application font size changes with the system.	String	Yes (initial value: nonFollowSystem)

icon

The icon tag represents the application icons and the index to the layered icon configuration files.

Layered icons can be configured as follows:

Place the foreground and background resources of the icon in the AppScope/resources/base/media directory.
Create a JSON file (for example, layered-image.json) in the media directory and reference the foreground and background resources in the file. For details, see Icon Resource Specifications.

Example of the layered icon resource file:

{
  "layered-image":
    {
      "background":"$media:background," // Background resource
      "foreground":"$media:foreground" // Foreground resource
    }    
}

Example of the icon structure:

{
  "app":{
    "icon":"$media:layered-image"
  }
}

appEnvironments

The appEnvironments tag represents the application environment variables. Applications may depend on some third-party libraries, which may use some custom environment variables. To avoid changing the implementation logic of the third-party libraries, you can set custom environment variables in the project configuration file for use during application running.

Table 2 appEnvironments

Name	Description	Data Type	Initial Value Allowed
name	Name of the environment variable. The value is a string with a maximum of 4096 bytes.	String	Yes (initial value: left empty)
value	Value of the environment variable. The value is a string with a maximum of 4096 bytes.	String	Yes (initial value: left empty)

Example of the appEnvironments structure:

{
  "app": {
    "appEnvironments": [
      {
        "name":"name1",
        "value": "value1"
      }
    ]
  }
}

multiAppMode

The multiAppMode tag represents the multi-app mode of the application.

Table 3 multiAppMode

Name	Description	Data Type	Initial Value Allowed
multiAppModeType	Multi-open mode. The options are as follows: - multiInstance: multi-instance mode. Only 2-in-1 devices are supported. A resident process does not support this value. - appClone: app clone mode.	String	No
maxCount	Maximum number of applications that can be opened. The options are as follows: - In multiInstance mode, the value ranges from 1 to 10. - In appClone mode, the value ranges from 1 to 5.	Number	No

Example of the multiAppMode structure:

{
  "app": {
    "multiAppMode": {
      "multiAppModeType": "appClone",
      "maxCount": 5
    }
  }
}

configuration

This tag is a profile file resource that used to specify the configuration file that describes the application font size changes with the system.

Example of the configuration structure:

{
  "app": {
    "configuration": "$profile:configuration"  
  }
}

Define the configuration.json file under AppScope/resources/base/profile in the development view. The file name (configuration in this example) can be customized, but must be consistent with the information specified by the configuration tag. The file lists the attributes that enable the application font size to change with the system.

Table 4 configuration

Name	Description	Data Type	Initial Value Allowed
fontSizeScale	Settings of the application font size. The options are as follows: - followSystem: The font size follows the system. - FollowSystem: The font size does not follow the system.	String	Yes (initial value: nonFollowSystem)
fontSizeMaxScale	Maximum ratio of the application font size after the font size is set to follow the system. The options are as follows: 1, 1.15, 1.3, 1.45, 1.75, 2, and 3.2. If fontSizeScale is set to nonFollowSystem, this attribute does not take effect.	String	Yes (initial value: 3.2)

Example of the configuration structure:

{
  "configuration": {
    "fontSizeScale": "followSystem",
    "fontSizeMaxScale": "3.2"
  }
}