pal-platform utility

This utility script deploys and generates platform-dependent files needed to build and run non-Mbed OS applications. It can run on both Linux and Windows.

The deployment instructions for supported targets are in pal-platform.json (located in the pal-platform folder in the root folder of the mbed-cloud-client repository).

Requirements

• We recommend Python 2.x version 2.7 or higher

• Git 2.

• If working under Windows: the patch.exe utility (this utility is already part of Git for Windows).

  Note: This must be in your system PATH.

• Python modules (install manually or using the requirements.txt provided under the pal-platform folder: pip install -r requirements.txt):

  • click: run pip install click (add sudo when running on Linux).
  • requests: run pip install requests (add sudo when running on Linux).

Usage

The script gets its default deployment instructions from pal-platform.json (located in the pal-platform folder in the root folder of the mbed-cloud-client repository), but you can also use your own custom deployment instructions *.json file using the --from-file flag.

~/mbed-cloud-client-example/pal-platform$ python pal-platform.py -h
Usage: pal-platform.py [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

Options:
  -v, --verbose     Turn ON verbose mode
  --from-file PATH  Path to a .json file containing the supported targets configuration.
                    Default is ~/mbed-cloud-client-example/pal-platform/pal-platform.json
  --version         Show the version and exit.
  -h, --help        Show this message and exit.

Commands:
  clean     Clean target-dependent files (run "pal-platform.py clean -h" for help)
  deploy    Deploy mbed-cloud-client files (run "pal-platform.py deploy -h" for help)
  generate  Generate target-dependent files (run "pal-platform.py generate -h" for help)
  fullbuild  fullbuild deploy and build the project (run "pal-platform.pyfullBuild -h" for help)

Deploy

This subcommand deploys platform-dependent files to a given target. It fetches the files from their source location to their required destination in the pal-platform folder and applies patches as needed:

~/mbed-cloud-client-example/pal-platform$ python pal-platform.py deploy -h
Usage: pal-platform.py deploy [OPTIONS]

  Deploy target-dependent files

Options:
  --target [x86_x64_NativeLinux_mbedtls]
                                  The target to deploy platform-dependent files for  [required]
  --skip-update                   Skip Git Repositories update
  -i, --instructions              Show deployment instructions for a given target and exit.
  -h, --help                      Show this message and exit.

Deployment instructions

If you want to see the deployment instructions for a target (without deploying it), use the -i/--instructions flag. The instructions are printed to stdout.

For example, on the x86_x64_NativeLinux_mbedtls target:

~/mbed-cloud-client-example/pal-platform$ python pal-platform.py deploy --target=x86_x64_NativeLinux_mbedtls -i
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ x86_x64_NativeLinux_mbedtls ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#################
# mbedtls  2.4.0
#################
- Clone [email protected]:ARMmbed/mbedtls.git at master to ~/mbed-cloud-client-example/pal-platform/Middleware/mbedtls/mbedtls

Generate

This subcommand generates the target's build directory in the form of __<TARGET_NAME> on the same level as the pal_platform directory. The build directory contains two files that CMake will use later: CMakeLists.txt and autogen.cmake.

~/mbed-cloud-client-example/pal-platform$ python pal-platform.py generate -h
Usage: pal-platform.py generate [OPTIONS]

  Generate files to be used by build-system

Options:
  --target [x86_x64_NativeLinux_mbedtls]
                                  The target to generate platform-dependent files for
  -h, --help                      Show this message and exit.

You can generate and deploy with a single command by using both generate and deploy:

python pal-platform.py deploy --target=x86_x64_NativeLinux_mbedtls generate

When the generate command has completed, you can run CMake and Make from the generated build directory.

Clean

This subcommand deletes the target's build directory and all the target's deployed files and directories.

Tip: You can use the --keep-sources flag to keep the target's deployed files and directories.

~/mbed-cloud-client-example/pal-platform$ python pal-platform.py clean -h
Usage: pal-platform.py clean [OPTIONS]

  Clean target-dependent files

Options:
  --target [x86_x64_NativeLinux_mbedtls]
                                  The target to clean  [required]
  -k, --keep-sources              Keep the deployed platform-dependent files
                                  (clean only generated files)
  -h, --help                      Show this message and exit.

fullbuild

This subcommand performs the deployment and generation steps and then generates the Makefile and builds the final binaries (both debug and release). You can make this happen through the following steps:

1. Run the deploy step (detailed above) for the given target.
2. Run the generate step (detailed above) for the given target.
3. Call 'cmake' to generate the Makefiles for debug binaries for the target toolchain using the external CMake configuration file provided.
4. Call make to make the binary provided in name option.
5. Copy the generated binaries to the out folder.
6. Delete the build directory generated by the generate step.
7. Repeat steps 2-5 for the release binaries.

Tip: The script creates the resulting binaries in the out folder it created for this purpose. The debug binaries are in the Debug subfolder and the release binaries in the Release folder

Options:
  --target [x86_x64_NativeLinux_mbedtls|ARM_OpenWRT_mbedtls|Yocto_Generic_YoctoLinux_mbedtls]
                                  The target to deploy and build  [required]
  --toolchain [ARMCC|ARMGCC|GCC|GCC-OPENWRT|POKY-GLIBC]
                                  The toolchain to use for the build
                                  [required]
  --external PATH                 The path of the eternal define CMake file to
                                  include
  --name PATH                     name of the build target passed to the make
                                  command
  -k, --keep-sources              Keep the deployed platform-dependent files
                                  (clean only generated files)
  -j INTEGER                      -j parallel make parameter (Example: -j4)
  -h, --help                      Show this message and exit.

Generating the Makefiles

If you use the manual approach (as opposed to the fullbuild command), the result after the generate step is a build directory, which contains CMake files. You can use the cmake tool to generate Makefiles from the build directory.

To generate the Makefiles, use the cmake command in the following way:

cmake  -G "<SYSTEM_GENERATOR>" -DCMAKE_BUILD_TYPE=<BUILD_TYPE> -DCMAKE_TOOLCHAIN_FILE=<TOOLCHAIN_RULES_FILE> -DEXTERNAL_DEFINE_FILE=<USER_CMAKE_FILE>

You can, and probably need to, give the following variables to generate Makefiles for the correct target:

Note: Before running the cmake command, make sure you configure the toolchain path in the correct environment variables for CMake because the script does not automatically detect the path the way it does with the fullbuild command.

For example, for the above configuration, you need the following commands for CMake to set up the right Makefiles:

cmake  -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=./../pal-platform/Toolchain/GCC/GCC.cmake

Tip: When generating the makefiles, CMake creates a compilation_info.txt file in the root folder. This file lists all the libraries that will be compiled and the source files compiled into each library.

Examples

For x86_x64_NativeLinux_mbedtls

x86_x64_NativeLinux_mbedtls content in pal-platform.json:

  "x86_x64_NativeLinux_mbedtls":
  {
    "device": {
      "name": "x86_x64"
    },
    "os": {
      "name": "Linux_Native"
    },
    "middleware": {
      "mbedtls": {
        "version": "2.4.2",
        "from": {
          "protocol": "git",
          "location": "[email protected]:ARMmbed/mbedtls.git",
          "tag": "mbedtls-2.4.2"
        },
        "to": "Middleware/mbedtls/mbedtls"
      }
    }
  },

deploy

~/mbed-cloud-client-example/pal-platform$ python pal-platform.py deploy --target=x86_x64_NativeLinux_mbedtls
2017-04-23 09:40:59,038 - pal-platform - INFO - Getting mbedtls from git
2017-04-23 09:40:59,038 - pal-platform - INFO - Cloning from [email protected]:ARMmbed/mbedtls.git at master to ~/mbed-cloud-client-example/pal-platform/Middleware/mbedtls/mbedtls
Deployment for x86_x64_NativeLinux_mbedtls is successful.
Deployment instructions are in ~/mbed-cloud-client-example/pal-platform/x86_x64_NativeLinux_mbedtls.txt.

generate

~/mbed-cloud-client-example/pal-platform$ python pal-platform.py generate --target=x86_x64_NativeLinux_mbedtls
2017-04-23 14:00:42,196 - pal-platform - INFO - Generated ~/mbed-cloud-client-example/__x86_x64_NativeLinux_mbedtls/autogen.cmake
Generation for x86_x64_NativeLinux_mbedtls is successful, please run cmake and make from ~/mbed-cloud-client-example/__x86_x64_NativeLinux_mbedtls

clean

~/mbed-cloud-client-example/pal-platform$ python pal-platform.py clean --target=x86_x64_NativeLinux_mbedtls
2017-04-23 14:02:47,325 - pal-platform - INFO - Deleting ~/mbed-cloud-client-example/pal-platform/__x86_x64_NativeLinux_mbedtls
2017-04-23 14:02:47,331 - pal-platform - INFO - Deleting ~/mbed-cloud-client-example/pal-platform/Middleware/mbedtls/mbedtls

fullbuild

Note: This is only a small snippet because the build generates a very long output.

python pal-platform/pal-platform.py fullbuild --target x86_x64_NativeLinux_mbedtls --toolchain ARMGCC
2018-02-01 15:03:03,063 - pal-platform - INFO - fullBuild running for target = x86_x64_NativeLinux_mbedtls with toolchain = ARMGCC
2018-02-01 15:03:03,064 - pal-platform - INFO - Getting mbedtls from git
2018-02-01 15:03:03,064 - pal-platform - INFO - /home/userf01/work/pal-example/pal-platform/Middleware/mbedtls/mbedtls already exists, updating from https://github.com/ARMmbed/mbedtls.git
2018-02-01 15:03:05,004 - pal-platform - INFO - Checking out from https://github.com/ARMmbed/mbedtls.git at mbedtls-2.4.2
Deployment for x86_x64_NativeLinux_mbedtls is successful.
Deployment instructions are in /home/userf01/work/pal-example/pal-platform/x86_x64_NativeLinux_mbedtls.txt.
2018-02-01 15:03:05,025 - pal-platform - INFO - Generated /home/userf01/work/pal-example/__x86_x64_NativeLinux_mbedtls/autogen.cmake
Generation for x86_x64_NativeLinux_mbedtls is successful, please run cmake & make from /home/userf01/work/pal-example/__x86_x64_NativeLinux_mbedtls
2018-02-01 15:03:05,026 - pal-platform - INFO - Checking Environment for Toolchain - ARMGCC
2018-02-01 15:03:05,042 - pal-platform - INFO - running cmake
2018-02-01 15:03:05,042 - pal-platform - INFO - setting environment: ARMGCC_DIR = /home/userf01/work/ARMGCC/
-- TOOLCHAIN_DIR: /home/userf01/work/ARMGCC/
-- BUILD_TYPE: Debug
flags file is /home/userf01/work/pal-example/__x86_x64_NativeLinux_mbedtls/../pal-platform/Toolchain/ARMGCC/ARMGCC-flags.cmake
/home/userf01/work/pal-example/__x86_x64_NativeLinux_mbedtls/include_file.txt
-- Toolchain file was set manualy!
-- cmake file found for Device in /home/userf01/work/pal-example/pal-platform/Device/x86_x64/x86_x64.cmake
-- cmake file found for os in  /home/userf01/work/pal-example/pal-platform/OS/Linux_Native/Linux_Native.cmake
-- No cmake file found for sdk in  /home/userf01/work/pal-example/pal-platform/SDK//.cmake
statusdevice = x86_x64
...