Leaf Workspace Manager

Leaf is a workspace manager that will download, install and configure the required software packages for a Legato development environment.

This tutorial will walk you through how to:

  • Install Leaf
  • Set up a remote to point to a package repository
  • Search for a package to install
  • Set up your development environment
  • Use the built in shell to access the development tools
  • Set up your workspace to start development

The basic workflow that should be followed to download and set up a development environment for your target. These tutorials use the packages that have been created for the Legato project as examples.

Install Leaf

Leaf is hosted in the Sierra Wireless debian tools repository, and is provided as a .deb package to be installed through apt. We have also provided alternative install instructions for older Ubuntu Distributions (14.04 and below) and instructions for manually installing from a tarball.

Install leaf download and set up our debian package from the Sierra Wireless tools repository: 

$ wget https://downloads.sierrawireless.com/tools/leaf/leaf_latest.deb -O /tmp/leaf_latest.deb && sudo apt install /tmp/leaf_latest.deb

Leaf installs tools, images and packages into the ~/.leaf/ directory; all configuration is stored in ~/.config/leaf/

Before searching and installing your first SDK it is recommended to make a separate leaf workspace directory to store all of your custom Legato development. For this site and tutorials we will be setting up the leaf workspace in $HOME/myWorkspace.

$ mkdir ~/myWorkspace; cd ~/myWorkspace

Search for Packages

Now that you have leaf installed, you can now search through a repository to find the packages to download, install and configure your Development Environment.

Warning
You are able to search leaf from anywhere on your computer; running leaf setup will add config in the directory that you are currently in. It is recommended to create a workspace dir and set up leaf packages from within your workspace.

leaf search

Using leaf search with no filters will list every package in any repository that you have enabled (it may be a huge list). It is better to search with filters that return a smaller list that is specific for your target.

Search for a Target

$ leaf search -t <target>    (i.e.; leaf search -t wp76xx will bring back all packages for the wp76 target)

The search results will return a package identifier (the package name of the package to install), a high level description of what is in the package, and the tags of the package. You are also able to search filter the search results by tag using the -t flag. 

$ leaf search -t latest          (returns all the newest/latest published packages for all targets)
$ leaf search -t wp76xx -t latest     (returns the latest packages for the wp76 target)

To see exactly what is contained in the package perform a search with a -v flag (verbose). This will list the details of what each package contains including the release date and the list of versions of all sub-packages listed as dependencies. 

$ leaf search -t wp76xx -t latest -v  (returns the details of the latest package for the wp76 target)

For details on each of the components of the package visit the vendors page. Firmware Details (including Yocto distribution, toolchain and firmware): source.sierrawireless.com Legato Details: Releases

Set up Development Environment

Now that you know which package that you want to install on your development machine, the next step is to run leaf setup. The setup command will prepare your directory as a workspace and download, install and configure your workspace with a profile (settings specific to your target and version) preparing you to start developing for your target.

$ leaf setup <profile name> -p <package identifier>

$ leaf setup wp76stable -p swi-wp76_1.0.0  (downloads and installs the swi-wp76_1.0.0 package in the wp76stable profile)
Note
Downloading and installing the package may take a few minutes. Leaf configures everything that is needed for you to start developing for your target including the toolchain, Legato application framework and other development tools. It will also take care of installing any apt dependencies. The apt dependencies will require sudo and you will be prompted for your password for sudo privileges.

After installation a new directory (leaf-data) and a new configuration file (leaf-workspace.json) will be created in your workspace directory. The directory contains symbolic links to all the resources needed for development and the leaf tools know how to find the resources for development.

You will now be able to use leaf commands to view your environment and use the resources that you just downloaded and installed. For detailed help on the leaf sub-commands see Leaf. 

$ leaf status - displays the profile list and information about the profiles
$ leaf select - lets you select different profiles (if you have more then one installed)
$ leaf profile delete <profile name>
$ leaf profile rename <old name> <new name> - renames your profile

Set up a 2nd Profile

To set up a second profile (if you wish to use multiple targets, or multiple versions) run the leaf setup command again and choose a new profile name. 

$ leaf setup <2nd profile> -p <2nd package identifier>

$ leaf setup wp76dev -p swi-wp76_1.0.0

To see the two profiles set up use leaf status and leaf select to switch between profiles. 

$ leaf status
$ leaf select <profile name>.

Leaf Shell

leaf shell provides an interactive shell that is profile aware to run all of your tools for your development environment. If you need to switch to a different profile (different target or version of software) the shell environment will update all environment variables to point to the version that matches the profile that you are working with.

Warning
shell is $PWD dependant; if you switch to another directory outside of your workspace you will lose your leaf environment variables, and it will not be profile aware (automatically switch to the toolchain and tools that match the profile you are using).

i.e.; Using mksys from within the leaf shell will use the version of the tool that is configured for that specific profile and will also build a Legato System with the correct toolchain. If you switch profiles and run mksys again it will use the version configured with the second profile and use the toolchain configured for the second profile environment.

Set up Workspace

Now that you have all your development environment set up and configured you are now able to start development.

All leaf packages are downloaded to $HOME/.leaf by default (see leaf config to update) and are used as references to be included in to your workspace via environment variables.

Any new environment variables that you would like added to your development environment can be added with leaf env. See leaf help env for details on adding new environment variables to either a profile or a workspace. 

$ leaf env profile --set MYVAR=1  (sets the environment variable MYVAR to 1 for the current profile)

Legato Development

Leaf enables a new style of Legato development that allows you to create your component, apps and systems in your own workspace instead of working directly in the Legato directory. This will keep your custom code separate and still allow a full build of Legato Systems. Any changes that you do make directly to the Legato Application Framework will be reflected in your system when you run mksys from within the leaf shell in your workspace.

If you do wish to use the Git tracked source code for Legato you are able to check-out the source code for Legato. This version requires you to have an account on Legato's Gerrit server. Use the command leaf getsrc legato to checkout the version of Legato that matches your profile.

Legato Workflow Changes

  • The version of Legato that you install is pre-built for your module, meaning that there is no need to run make, or set-up the toolchain and other configuration tasks.
  • You do not need to run bin/legs or source bin/configlegatoenv in your bash.rc file. The leaf shell makes sure that all environment variables are set up and are aware of the specific version of Legato that you are using within each profile.
  • Do not add your apps and settings to default.sdef you are now able to #include default.sdef in an sdef in your workspace and build not only your settings but all the default legato apps and configuration.
Note
Because you are now working with a pre-built version of Legato, any changes that you do make to the Legato Application Framework are not tracked, if you wish to modify the framework and build from source code see leaf help legato-source to download and connect tracked Legato source code.

Set-up SDEF

Using your own .sdef file is easy to set up and maintain. Using this method leaves all the Legato configuration in default.sdef and allows you to quickly see and work with your customization to your Legato System.

Create a new .sdef file in your leaf workspace: 

$ vim mySystem.sdef (or the editor of your choice)

In mySystem.sdef use the following line to include all the default Legato settings: 

#include $LEGATO_ROOT/default.sdef

You are also able to include any other .sdef files you wish using the same method.

A couple of very useful environment variables that are set up in Legato:

  • $LEGATO_ROOT - resolves to the location of the Legato Application Framework for your profile
  • $CURDIR - resolves to the directory where you run the mktools from (i.e.; add $CURDIR/path/to/your/app to the apps section of your .sdef and then run mksys from your workspace directory to build your apps into the update file)

To build your system you no longer need to re-make the build. Run mksys and point it at your .sdef. To build a Legato System using your custom sdef run: 

$ mksys -t $LEGATO_TARGET <sdef>   (i.e.; mksys -t wp76xx mySystem.sdef from your leaf workspace directory)

Workspace Layout

Because you are not working directly in the Legato directory anymore, we recommend setting up a directory structure that will be easy to use and organize your apps, kernel modules and other settings for the Legato Application Framework. Remember to use $CURDIR to reference the workspace folder in your .sdef.

Example directory structure using the helloWorld app: 

  .
  ├── apps
  │   └── helloWorld
  │       ├── CMakeLists.txt
  │       ├── helloComponent
  │       │   ├── Component.cdef
  │       │   └── helloWorld.c
  │       └── helloWorld.adef
  ├── components
  |       └── ... (a directory for each component)
  ├── drivers
  |       └── ... (a directory for each kernel module)
  ├── interfaces
  |       └── ... (all apis that your apps export)
  ├── leaf-data
  │   └── ... (leaf symbolic links, do not edit)
  ├── leaf-workspace.json
  └── mySystem.sdef

This is just an example of how you could set up your directory structure, it is up to you and how you connect all of your components, apps and system in your workspace. Working out of the workspace directory lets you easily work with different profiles and switch to a new profile (target and/or version of Legato) and continue to use your same components, apps and/or system to build for your target devices.

Workflows

The Leaf workflow design includes a hierarchy and is set up with the first install of a leaf package:

  • USER (universal config for all workspace and profiles)
  • WORKSPACE (the working directory for your code and your customization)
  • PROFILE (target/version specific configuration and settings)

See leaf help legato-workflow for more details on the relationship between profiles, workspaces and users.

Copyright (C) Sierra Wireless Inc.