Skip to content

Usage ProjectsAndPackages

Jump to bottom
marchbold edited this page Jun 22, 2023 · 8 revisions

Projects and Packages

The following details how to use apm to initialise a project and install packages.

Project

Initialise

A new project definition file can be created by using the init command:

apm init

This will run through a series of questions to setup a basic project.apm file. This file is referred to as the "Project Definition File" and represents the configuration of your application including all the requested package dependencies. All the commands in the section reference the project definition file in the current directory in order to operate. You should run this in the root of your application code, generally we consider this to be alongside your src directory where the source code for your application is.

Example:

$ apm init
Creating new project definition file
Application Identifier [com.my.app]: com.apm.test
Application Name [My Application]: APM Test
Application Consts [1.0.0]:

Creates a project definition file, eg:

{
  "name": "APM Test",
  "id": "com.apm.test",
  "version": "1.0.0",
  "repositories": [],
  "configuration": {},
  "dependencies": []
}

Project Parameters

You can manually edit the project.apm file to edit the fields as you require however there are a few commands that you can use to modify certain aspects. The values that can be edited through here can also be used within build configurations so you can specify a different identifier for each build type if you require.

Supported values are:

  • identifier
  • filename
  • name
  • version
  • versionLabel
  • platforms (see platforms documentation for further information on this)

Get

You can list the project parameters by calling

apm project get

Set

To change the main identifier:

apm project set identifier com.apm.test

Add

To add a value to an array type (eg platforms) you can use the add command:

apm project add platforms macos

Configuration

This command allows you to set and get parameters that are used for extensions when generating your application descriptor.

Get

To list the current configuration you can call apm project config or apm project config get. This will list out all the current configuration parameters and their current values.

For example:

$ apm project config get

facebookAdvertiserIDCollectionEnabled=true
facebookAppId=
facebookAutoInitEnabled=true
facebookAutoLogAppEventsEnabled=true
facebookDisplayName=Facebook app name
photoLibraryAddUsageDescription=Access to photo library is required to save images and videos.
photoLibraryUsageDescription=Access to photo library is required to save images and videos.
somekey=avalue
test=value
userTrackingUsageDescription=Allows us to deliver personalized ads for you.

You can retrieve a single parameter value using:

apm project config get <param>

where <param> is the name of the parameter to retrieve.

Describe

If you need help understanding what the configuration parameters represent you can use the describe command:

apm project config describe <param>

where <param> is the name of the parameter to retrieve. If you omit the parameter name then the description of all the parameters will be displayed.

For example:

$ apm project config describe facebookAppId

# [com.distriqt.facebook.Core]: The App ID for your Facebook application
#         See https://docs.airnativeextensions.com/docs/facebookapi/get-started
facebookAppId=XXXXXXXXX (required)

You will note that the package identifier that uses this parameter is displayed along with the description from the package. If multiple packages use the same parameter then the description from each package will be printed beside the package identifier.

You can alternatively specify a package identifier instead of the parameter name to describe all the configuration parameters related to a package:

apm project config describe com.distriqt.PushNotifications

# [com.distriqt.PushNotifications]: no description provided
bundleSeedId=XEQEWRST (required)

# [com.distriqt.PushNotifications]: no description provided
apsEnvironment=development (required)

# [com.distriqt.PushNotifications]: no description provided
getTaskAllow=false (required)

Set

To set or update a configuration parameter value you use the set command.

You can set a parameter directly by passing the parameter name and the value to the command:

apm project config set <param> <value>
  • <param> is the name of the parameter to set/get;
  • <value> is the new value for the parameter;

For example:

$ apm project config set facebookAppId 1234567890

This will add or update the configuration value in your project.apm

{
  "configuration": {
    "facebookAppId": {
      "name": "facebookAppId",
      "required": "true",
      "value": "1234567890"
    }
  },
  "name": "APM Test",
  "id": "com.apm.test",
  "version": "1.0.0",
  "dependencies": [],
  "repositories": []
}

You will find that when packages are installed some default values may be inserted into the configuration object. You may have to edit these to reflect your particular requirements or settings.

Set via Input

There are several additional uses of the set command which will walk you through the parameters asking for input to help configure your project.

Firstly if you specify a parameter name but no value, the parameter description will be printed and you will be able to input a value for the parameter, eg:

apm project config set photoLibraryAddUsageDescription

# [com.distriqt.facebook.Core]: no description provided
photoLibraryAddUsageDescription=Access to photo library is required to save images and videos. (required)
Set [Access to photo library is required to save images and videos.]: _

You then type in a value and press enter to store the value. If you just press enter the value will remain unchanged.

If you specify a package identifier instead of a parameter name, then you will be presented each of the package configuration parameters and asked to enter a value for each.

apm project config set com.distriqt.PushNotifications

# [com.distriqt.PushNotifications]: no description provided
bundleSeedId=XEQEWRST (required)
Set [XEQEWRST]:

# [com.distriqt.PushNotifications]: no description provided
apsEnvironment=production (required)
Set [production]:

# [com.distriqt.PushNotifications]: no description provided
getTaskAllow=false (required)
Set [false]:

If you just call apm project config set (with no parameter name or value)then you will be presented all of the project configuration parameters and asked to enter a value for each.

apm project config set

# [com.distriqt.PushNotifications]: no description provided
apsEnvironment=production (required)
Set [production]:

# [com.distriqt.PushNotifications]: no description provided
bundleSeedId=XEQEWRST (required)
Set [XEQEWRST]:

# [com.distriqt.PushNotifications]: no description provided
getTaskAllow=false (required)
Set [false]:

# [com.distriqt.GameServices]: no description provided
playGamesAppId=XXXXXXXX (required)
Set [XXXXXXXX]:

# [com.distriqt.IDFA]: no description provided
userTrackingUsageDescription=Allows us to deliver personalized ads for you. (required)
Set [Allows us to deliver personalized ads for you.]:

Build Types

Build types expand upon the configuration parameters allowing you to create different versions of your app from a single project.

Using build types you can specify a different set of configuration parameters to be used for a build, for example, you may have a set of configuration values for development and production.

You specify the build type for apm to use by passing a -build <type> option to the command, eg to get the development configuration parameters:

apm -build development project config get

This applies to all commands that use or edit the project configuration parameters.

This option must be supplied before the apm command, i.e. apm <options> <command>. Supplying this after the apm command will fail.

Configure build types

To create a build type, simply specify the name as the -build or -b parameter and set a project or configuration value.

You can use build types for any of the support project parameters or configuration parameters.

For example:

apm -b development project set identifier com.apm.debug
apm -b development project config set apsEnvironment development

Results in the following build type in your project file:

"configuration": {
  "apsEnvironment": {
      "name": "apsEnvironment",
      "required": "true",
      "value": "production"
  },
},
"buildTypes": {
  "development": {
      "identifier": "com.apm.debug",
      "configuration": {
          "apsEnvironment": "development"
      }
  }
}

You can then verify the different configuration sets, the default:

apm project config get
apsEnvironment=production

And the development build type:

apm -build development project config get
apsEnvironment=development

You can then apply these configuration sets to an application descriptor, for example to generate the default application descriptor:

apm generate app-descriptor MyApp-app.xml

And to generate the development descriptor:

apm -build development generate app-descriptor MyApp-app-development.xml

Platforms

You can limit your project to a series of platforms if you wish to limit apm to creating and deploying the extensions, libraries and assets that are required for your specific platforms. Packages that contain content specific to a platform (or platforms) will only be deployed if your application requires it.

By default, apm assumes your application supports all platforms. Generally this isn't an issue, even if you are only deploying to one platform, however if you do want to limit the assets and extensions added to your application this allows you to control that.

To limit your application to specific platforms, set the platforms your project supports by adding them to your project:

apm project set platforms android,ios

or

apm project add platforms android
apm project add platforms ios

Now whenever any of the other commands are run, apm will only process the required platforms.

Note

If you are adding this to an existing project, you should delete the deployed assets and ane folders and run apm install again.

Packages

Only packages that support this option will be processed. If the package hasn't been updated to support this option then they will be assumed to be used on all platforms. So you may have to wait for a package to be updated to support platforms before this will have any direct affect.

Packages

Packages are containers for AIR libraries, such as swc's, ane's and packaged source code. You can use apm to install and update packages in your project.

All these commands require a project definition file in the current directory.

List

Lists the installed packages in the current project.

apm list

This command references the current project definition and lists out the currently installed packages and versions

$ apm list
APM Test@1.0.0 /path/to/app
├──com.distriqt.IDFA@5.0.29
└──com.distriqt.SystemGestures@1.0.18

Search

This command connects with the APM repository and performs a search for the specified keyword.

apm search <query>

For example:

$ apm search idfa
✓ Search complete
found [1] matching package(s) for search 'idfa'
└──com.distriqt.IDFA@5.0.29   The IDFA extension gives you simple access to the advertising identifiers on Android and iOS

View

Once you have identified a package you can get additional details on the package through the view command.

apm view <package_identifier>

This prints the description, tags and available versions of the package.

For example:

$ apm view com.distriqt.IDFA
com.distriqt.IDFA@5.0.29   The IDFA extension gives you simple access to the advertising identifiers on Android and iOS.
tags
└── [ advertising android app-tracking-transparency identifier idfa ios  ]
versions
├──5.0.29 : 2021-06-15T02:57:51.767Z
└──5.0.28 : 2021-05-15T02:57:51.767Z

Install

You can now install a package by using the install command:

apm install <package_identifier>

This will trigger a series of processes that will download and install the latest version of the package, along with required dependencies. If you have any other installed packages the process will also attempt to resolve any conflicts between dependencies automatically selecting a version to install (if possible). There will be times when this process will fail, you may need to update existing packages before continuing.

Packages will be downloaded into an apm_packages directory. This is like a local cache and working directory for the package manager. We suggest adding this directory to your .gitignore file (or similar).

As a last step in this process the packages will be extracted and "deployed". Deploying means extracting the library from the package and making available in a location for your application code. The exact deployment locations are dependent on the type of package and will be discussed more later.

For example, the following installs the com.distriqt.IDFA extension and you can see the androidx.core and com.distriqt.Core extensions being installed automatically:

$ apm install com.distriqt.IDFA
com.distriqt.IDFA@5.0.29
androidx.core@1.5.0
com.distriqt.Core@6.4.1
Installing package : androidx.core@1.5.0
✓ downloaded
✓ extracted
Installed package : androidx.core@1.5.0
Installing package : com.distriqt.IDFA@5.0.29
✓ downloaded
✓ extracted
Installed package : com.distriqt.IDFA@5.0.29
Installing package : com.distriqt.Core@6.4.1
✓ downloaded
✓ extracted
Installed package : com.distriqt.Core@6.4.1
✓ Deployed: androidx.core@1.5.0
✓ Deployed: com.distriqt.IDFA@5.0.29
✓ Deployed: com.distriqt.Core@6.4.1

If you wish to install a specific version of a package you can do so with an optional parameter:

apm install <package_identifier> <version>

For example:

apm install com.distriqt.IDFA 5.0.28

The default is to install the latest version, and is the equivalent to:

apm install com.distriqt.IDFA latest

Uninstall

You may wish to uninstall a package at some point. To do this use the uninstall command:

apm uninstall <package_identifier>

This process will go through and identify any dependencies (that aren't used by other packages) and uninstall them as well. It will remove any files in the apm_packages directory associated with the package and remove any files that have been deployed.

For example:

$ apm uninstall com.distriqt.IDFA
Uninstall package : com.distriqt.IDFA
✓ Removed package : com.distriqt.IDFA
Uninstall package : androidx.core
✓ Removed package : androidx.core
Uninstall package : com.distriqt.Core
✓ Removed package : com.distriqt.Core

If one of these dependencies was required by another extension then we'd see something like the following:

$ apm uninstall com.distriqt.IDFA
Uninstall package : com.distriqt.IDFA
✓ Removed package : com.distriqt.IDFA
Uninstall package : androidx.core
✓ Removed package : androidx.core
Uninstall package : com.distriqt.Core
com.distriqt.Core :: Required by another package - skipping uninstall

Uninstall Update App Descriptor

You may also wish to update a specific application descriptor at this point to remove the extensionID (if this package is an ANE).

To do so pass the path to the application descriptor as a parameter to the uninstall command:

apm uninstall <package_identifier> <app_descriptor_path>

For example:

$ apm uninstall com.distriqt.IDFA src/MyApp-app.xml

Uninstall package : com.distriqt.IDFA
✓ Removed package : com.distriqt.IDFA
✓ Updated app descriptor : src/Test-app.xml
...

Outdated

This command will check the registry to see if any updates are available for the packages you currently have installed.

For example, the following output indicates there is an update to the com.distriqt.facebook.Core package from the installed version of 9.3.1 to 9.3.2:

$ apm outdated

identifier                   installed      available
com.distriqt.facebook.Core   9.3.1          9.3.2
com.distriqt.IDFA            5.0.31         5.0.31

By default this will only list the project dependencies you have installed directly in your project and not all the package dependencies. You can check the package dependencies as well by passing the --all parameter.

For example:

$ apm outdated --all

identifier                                installed      available
com.distriqt.facebook.Core                9.3.1          9.3.2
com.jetbrains.kotlin                      1.4.10         1.4.10
com.android.installreferrer               1.0.0          1.0.0
com.distriqt.Bolts                        4.2.1          4.2.1
com.distriqt.IDFA                         5.0.31         5.0.31
com.distriqt.Core                         6.4.3          6.4.3
com.distriqt.playservices.Base            17.5.1         17.5.1
androidx.core                             1.3.2          1.3.2
com.distriqt.playservices.AdsIdentifier   17.0.0         17.0.0

If you have access to a colour terminal the packages that have updates available will be highlighted.

Update

You will likely want to update the packages you have installed at some point. This process does several things, firstly it will go through your installed packages and determine if there is a more recent version available in the repository. If there is then the existing version will be removed and the new version installed. This is similar to calling uninstall <package> then install <package> latest but with some added advantages that all packages are done simulataneously.

For example if we had v5.0.28 of the IDFA package and the latest version of the SystemGestures package as seen in the project definition:

{
  "identifier": "com.apm.test",
  "name": "APM Test",
  "version": "1.0.0",
  "dependencies": [
    {
      "version": "1.0.18",
      "id": "com.distriqt.SystemGestures"
    },
    {
      "version": "5.0.28",
      "id": "com.distriqt.IDFA"
    }
  ],
  "configuration": {},
  "repositories": []
}

Then run the update command:

$ apm update
com.distriqt.IDFA@5.0.29
Uninstall package : com.distriqt.IDFA
✓ Removed package : com.distriqt.IDFA
Uninstall package : androidx.core
✓ Removed package : androidx.core
Uninstall package : com.distriqt.Core
com.distriqt.Core :: Required by another package - skipping uninstall
com.distriqt.SystemGestures@1.0.18
androidx.core@1.5.0
com.distriqt.Core@6.4.1
com.distriqt.Core@6.3.23
✓ removed com.distriqt.Core@6.3.23
Installing package : com.distriqt.SystemGestures@1.0.18
✓ Package already downloaded
✓ extracted
Installed package : com.distriqt.SystemGestures@1.0.18
Installing package : com.distriqt.Core@6.4.1
✓ downloaded
✓ extracted
Installed package : com.distriqt.Core@6.4.1
Installing package : com.distriqt.IDFA@5.0.29
✓ downloaded
✓ extracted
Installed package : com.distriqt.IDFA@5.0.29
Installing package : androidx.core@1.5.0
✓ downloaded
✓ extracted
Installed package : androidx.core@1.5.0
✓ Deployed: com.distriqt.SystemGestures@1.0.18
✓ Deployed: com.distriqt.Core@6.4.1
✓ Deployed: com.distriqt.IDFA@5.0.29
✓ Deployed: androidx.core@1.5.0

During this process you will see the output identifying a newer version of IDFA and then uninstalling the existing version. It then proceeds to install the newer versions and resolves some conflicts with the Core extension, choosing v6.4.1 over the existing v6.3.23.

Afterwards you will find the project definition file has been updated to include these versions of the packages:

{
  "identifier": "com.apm.test",
  "name": "APM Test",
  "version": "1.0.0",
  "dependencies": [
    {
      "version": "1.0.18",
      "id": "com.distriqt.SystemGestures"
    },
    {
      "version": "5.0.29",
      "id": "com.distriqt.IDFA"
    }
  ],
  "configuration": {},
  "repositories": []
}

Updating APM

A special note on the update command is that it has the ability to update the apm utility.

It will check for a more recent release and install it if available.

It is initiated by calling apm update and passing apm in place of the normal package identifier:

apm update apm

apm: v0.0.4-beta
✓ Already at latest version

It will output the current version and then check for any updates.

airsdk

APM

Background

  1. Concept

Client

Development

Clone this wiki locally