Building Multi-Target Products

This section describes the process and method of building multi-target products based on a case. In this case, two product projects can be built based on the same set of source code: official version and test version. The implementation effects of the two projects are as follows:

Official version: The resources of the official version and a page redirection button are displayed on the home page of the project. The page is a HAP module page. You can tap the button to go to the customized page of the official version. This page is a HAR module page, which contains a calculator. This calculator supports addition and subtraction.

Test version: The resources of the test version and a page redirection button are displayed on the home page of the project. The page is a HAP module page. You can tap the button to go to the customization page of the test version. This page is an HAR module page, which contains a common calculator. This calculator supports only subtraction.

This case includes the customization items related to the HAP, HAR, and app. The differences are as follows:

1. Break down the requirement and determine the product and target information based on the specific service scenario.

   According to the preceding case design and customization item table, two product versions need to be customized, that is, the official version and test version. Each product depends on two modules: a HAP module and a HAR module.

2. Customize the target content.

   HAP module: Configure the target in the module-level build-profile.json5 file.

   "targets": [
     {
       "name": "official",
       "source": {
         "pages": [
           "pages/Index"
         ],
         "sourceRoots": [
           "./src/official_pages"
         ]
       },
       "resource": {
         "directories": [
           "./src/main/official/resources",
           "./src/main/resources"
         ]
       }
     },
     {
       "name": "test",
       "source": {
         "pages": [
           "pages/Index"
         ],
         "sourceRoots": [
           "./src/test_pages"
         ]
       },
       "resource": {
         "directories": [
           "./src/main/test/resources",
           "./src/main/resources"
         ]
       }
     },
   ]

   In the preceding configuration file code, the target name, source code set pages, source code set sourceRoots, and resource file directory of the official and test versions are configured. Therefore, you need to create the configured files and directories in the corresponding directory structure. Based on the preceding configuration, you need to create the Index.ets file in the pages directory, the test_pages and official_pages directories in the src directory, and the test/resources and official/resources directories in the src/main directory.

   You can configure multiple resource file directories for different targets. You are advised to place the shared resource files in the default resource file directory and place the differentiated resource files in the customized resource file directory. When configuring the resource directories, add the default resource directory and customized resource directory. In this example, two resource directories are configured for different versions. One is used to store common resources, and the other is used to store differentiated resources of different targets.

   If resources with the same name exist in the specified directories, the resources are used based on the sequence in which the directories are configured. For example, if the official/resources and resources directories referenced by the official target contain resource files with the same name, the resources in the official/resources directory will be packaged into the HAP.

   * In the configuration file, default is the target generated by default during project creation. Generally, no special processing is required.

   HAR module: Configure the target in the module-level build-profile.json5 file.

   "targets": [
     {
       "name": "official",
       "config": {
         "buildOption": {
           "arkOptions": {
             "buildProfileFields": {
               "productName": "official"
             }
           },
           "nativeLib": {
             "filter": {
               "excludes": [
                 "../libs/arm64-v8a/libentry.so"
               ]
             }
           }
         }
       },
       "runtimeOS": "HarmonyOS",
       "output": {
         "artifactName": "official"
       },
       "source": {
         "sourceRoots": [
           "./src/official_pages"
         ]
       },
       "resource": {
         "directories": [
           "./src/main/official/resources",
           "./src/main/resources"
         ]
       }
     },
     {
       "name": "test",
       "config": {
         "buildOption": {
           "arkOptions": {
             "buildProfileFields": {
               "productName": "test"
             }
           }
         }
       },
       "runtimeOS": "HarmonyOS",
       "output": {
         "artifactName": "test"
       },
       "source": {
         "sourceRoots": [
           "./src/test_pages"
         ]
       },
       "resource": {
         "directories": [
           "./src/main/test/resources",
           "./src/main/resources"
         ]
       }
     }
   ]

   In the preceding configuration file code, the target name, buildProFields custom parameter, product name, source code set sourceRoots, and resource file directory of the official and test versions are configured, and the .so files that do not need to be packaged are deleted from the official version. Similarly, the required file directories need to be created, such as test/resources and official/resources folders in the src/main/ directory of the HAR module, as well as the official_pages and test_pages folders in the src/ directory.

3. Customize the product content.

   App project: Configure the target in the project-level build-profile.json5 file.

   {
     "app": {
       "signingConfigs": [],
       "products": [
         {
           "name": "official",
           "compatibleSdkVersion": "5.0.5(17)",
           "targetSdkVersion": "5.0.5(17)",
           "runtimeOS": "HarmonyOS",
           "buildOption": {
             "strictMode": {
               "caseSensitiveCheck": true,
               "useNormalizedOHMUrl": true
             }
           },
           "bundleName": "com.official.com",
           "bundleType": "app",
           "icon": "$media:startIcon",
           "label": "$string:official_app_name"
         },
         {
           "name": "test",
           "compatibleSdkVersion": "5.0.5(17)",
           "targetSdkVersion": "5.0.5(17)",
           "runtimeOS": "HarmonyOS",
           "buildOption": {
             "strictMode": {
               "caseSensitiveCheck": true,
               "useNormalizedOHMUrl": true
             }
           },
           "bundleName": "com.test.com",
           "bundleType": "app",
           "icon": "$media:app_icon",
           "label": "$string:test_app_name"
         },
         {
           "name": "default",
           "compatibleSdkVersion": "5.0.5(17)",
           "targetSdkVersion": "5.0.5(17)",
           "runtimeOS": "HarmonyOS",
         }
       ],
       "buildModeSet": [
         {
           "name": "debug",
         },
         {
           "name": "release"
         }
       ]
     },
     "modules": [
       {
         "name": "entry",
         "srcPath": "./entry",
         "targets": [
           {
             "name": "official",
             "applyToProducts": [
               "official"
             ]
           },
           {
             "name": "test",
             "applyToProducts": [
               "test"
             ]
           }
         ]
       },
       {
         "name": "myhar",
         "srcPath": "./myhar"
       }
     ]
   }

   In this configuration file, the product name, product bundle name (bundleName), signing configuration, app icon, and dependent target are configured. Note that the dependencies must be configured for the module that references the HAR module. In this example, the HAR package is called in the entry module. Therefore, you need to configure dependencies in the corresponding oh-package.json5 file.

4. Customize service logic to implement different target products.
   • Use the differentiated code spaces configured in sourceRoots to implement the multi-target title (code file).

     

     In the preceding configuration file, the source code set sourceRoots of the HAP module is configured, and their official version and test version correspond to src/official_pages and src/test_pages respectively.

     Create an .ets file with the same name and a method of the same type in the corresponding sourceRoots directory. For example, the VersionInfo.ets file is created in the example. Add the following code:

     src/official_pages/VersionInfo.ets

     export const getName = () => "This is official version."
     export const getTitleName = () => $r('app.string.title')

     src/test_pages/VersionInfo.ets

     export const getName = () => "This is test version."
     export const getTitleName = () => $r('app.string.title')

     In the Index.ets file, you can use import packageName without sourceRoot to implement differentiated build under different targets (import xxx from '<packageName>/sourceFileName'). For details about this capability, see sourceRoots.

     import { MainPage } from 'myhar'
     import { getName, getTitleName } from 'entry/VersionInfo'
     
     @Entry
     @Component
     struct Index {
       @State message: string = getName();
       @State titleMessage: Resource = getTitleName();
     
       build() {
         Column() {
           Column() {
             Text(this.titleMessage)
               .height(40)
               .fontSize(30)
               .fontWeight(FontWeight.Medium)
             Text(this.message)
               .fontSize(14)
               .fontWeight(FontWeight.Normal)
               .fontColor(Color.Black)
               .opacity(0.6)
               .height(19)
               .margin({ top: 2 })
           }
           .height(78)
           .width('100%')
           .alignItems(HorizontalAlign.Start)
           .padding({
             left: 12,
             right: 12,
             top: 8,
             bottom: 12
           })
     
           Row() {
             MainPage()
               .backgroundColor('#F1F3F5')
           }
           .layoutWeight(1)
         }
         .width('100%')
         .height('100%')
         .backgroundColor('#F1F3F5')
         .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM])
       }
     }

   • Reference differentiated resources in the HAR module to implement the multi-target effect of resources on the page.

     

     In the preceding configuration file, the resource file paths for the HAR module are configured, with the official version mapping to src/main/official/resources and the test version to src/main/test/resources.

     Add the image resource with the same name and JSON string to the corresponding resource file directory. For example, add the HarImage.jpg image with the same name (but different image content) to the media file in the resource file directory, and add the title_description parameter with the same name (but a different value) to the string.json file in the element file.

     Directly reference the resource with the same name on the page. The code is as follows:

     TextArea({ text: $r('app.string.title_description') })
       .fontSize(16)
       .width('100%')
       .fontColor('#e6000000')
       .fontWeight(FontWeight.Normal)
       .borderRadius(16)
       .focusable(false)
     Image($r('app.media.HarImage'))
       .width('100%')
       .borderRadius(12)
       .padding({ top: 16 })

   • In the HAR module, a user can be redirected to different pages based on different custom parameters to implement the multi-target effect of route.
     The effect comparison is as follows:

     Figure 1 Official version
     

     Figure 2 Test version
     

     The previous case describes how to call the same-name method of the same-name file in the differential code spaces configured in the sourceRoots directory. The following describes how to call different methods of different files in different targets.

     First, generate a BuildProfile.ets file based on the custom parameters configured in the configuration file. In the configuration file of the HAR module, the buildProfileFields custom parameter productName is configured, and it is set to official and test respectively in the official and test versions. In this way, different productName values are generated for different product versions, which are used to distinguish different product versions in the code project.

     Then, create different .ets files in the sourceRoots directories of official and test versions and export the corresponding components. In the example, OfficialSecondPages.ets is created in the src/official_pages directory of the HAR module and an OfficialSecond component is exported, create TestSecondPages.ets in the src/test_pages directory and export a TestSecond component. The two components contain different page information.

     Import the corresponding method on the home page to implement the redirection logic. The code is shown below:

     Import method and component:

     import BuildProfile from '../../../../BuildProfile';
     import { OfficialSecond } from '../../../official_pages/OfficialSecondPage';
     import { TestSecond } from '../../../test_pages/TestSecondPage';

     Define the page redirection logic: Different pages are displayed when different parameter values are received.

     @Builder
     PagesMap(name: string) {
       if (name == 'official') {
         OfficialSecond();
       } else {
         TestSecond();
       }
     }

     Add the click attribute for the button and pass custom parameters to implement navigation route.

     Button($r('app.string.button_describe'))
       .fontSize(16)
       .height(40)
       .width('100%')
       .onClick(() => {
         this.pageInfos.pushPath({ name: BuildProfile.productName });
       })

5. Select different products to build different target products.
   Figure 3 Build operations
   

   Click Product (marked as ① in the figure) in the upper right corner of DevEco Studio. Select the corresponding product project in the area marked as ② in the figure. After the project is selected, the dependent target in the file is automatically mapped. Then, click Apply. After the preceding operations are complete, you can click the run button to view the multi-target product effect. The following figure shows the running effect of this case.

   Figure 4 Official version

   

   Figure 5 Test version