<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html data-context="Build Apps" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type"/>
<title>Leaf Workspace Manager  - Legato Docs</title>
<meta content="legato™ is an open source Linux-based embedded platform designed to simplify connected IoT application development" name="description"/>
<meta content="legato, iot" name="keywords"/>
<meta content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" name="viewport"/>
<meta content="21.05.0" name="legato-version"/>
<link href="resources/images/legato.ico" rel="shortcut icon"/>
<link href="resources/images/legato.ico" rel="icon" type="image/x-icon"/>
<link href="resources/images/legato.ico" rel="shortcut icon" type="image/x-icon"/>
<link href="resources/images/legato.ico" rel="apple-touch-icon" type="image/x-icon"/>
<link href="resources/css/style.css" media="screen" rel="stylesheet" type="text/css"/>
<link href="resources/css/font-awesome.css" rel="stylesheet" type="text/css"/>
<!--[if IE]>
    <script src="resources/js/html5shiv.js"></script>
    <script src="resources/js/respond.js"></script>
  <![endif]-->
<script src="https://code.jquery.com/jquery-2.2.3.min.js"></script>
<script src="resources/js/main.js"></script>
<script src="tocs/Build_Apps_Get_Started.json"></script>
</head>
<body>
<noscript>
<input class="modal-closing-trick" id="modal-closing-trick" type="checkbox"/>
<div id="nojs">
<label for="modal-closing-trick">
<span>You seem to not have Javascript <a href="http://enable-javascript.com">enabled</a>, so site functionality like the search and navigation tree won't work.</span>
</label>
</div>
</noscript>
<div class="wrapper">
<div class="fa fa-bars documentation" id="menu-trigger"></div>
<div id="top">
<header>
<nav>
<a class="navlink" href="/">Introduction</a><a class="navlink selected" href="buildAppsMain.html">Build Apps</a><a class="navlink" href="buildPlatformMain.html">Build Platform</a><a class="navlink" href="aboutMain.html">About</a>
</nav>
</header>
</div>
<div class="white" id="menudocumentation">
<header>
<a href="/"> <img alt="Back to Legato Homepage" id="logo" src="resources/images/legato_logo.png"/></a>
<h2>/ Build Apps</h2>
<nav class="secondary">
<a class="link-selected" href="getStarted.html">Get Started</a><a href="concepts.html">Concepts</a><a href="apiGuidesMain.html">API Guides</a><a href="tools.html">Tools</a><a href="howToMain.html">How To</a><a href="experimentalMain.html">Experimental Features</a><a href="migrationGuide.html">Linux 4.14 Migration Guide</a>
</nav>
<nav class="ui-front">
<i class="fa fa-search" id="search-icon"></i>
<input id="searchbox" placeholder="Search"/>
</nav>
</header>
</div>
<div id="resizable">
<div id="left">
<div id="tree1"></div>
</div>
</div>
<div class="content">
<div class="header">
<div class="headertitle">
<h1 class="title">Leaf Workspace Manager </h1> </div>
</div><div class="contents">
<div class="textblock"><p>Leaf is a workspace manager that will download, install and configure the required software packages for a Legato development environment.</p>
<p>This tutorial will walk you through how to:</p><ul>
<li>Install Leaf</li>
<li>Set up a remote to point to a package repository</li>
<li>Search for a package to install</li>
<li>Set up your development environment</li>
<li>Use the built in shell to access the development tools</li>
<li>Set up your workspace to start development</li>
</ul>
<p>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.</p>
<h1><a class="anchor" id="confLeafInstall"></a>
Install Leaf</h1>
<p>Leaf is hosted in the Sierra Wireless debian tools repository, and is provided as a <code></code>.deb package to be installed through <code>apt</code>. We have also provided <a class="el" href="confLeaf_Install.html">alternative install instructions</a> for older Ubuntu Distributions (14.04 and below) and instructions for manually installing from a tarball.</p>
<p>Install leaf download and set up our debian package from the Sierra Wireless tools repository: </p><pre class="fragment">$ wget https://downloads.sierrawireless.com/tools/leaf/leaf_latest.deb -O /tmp/leaf_latest.deb &amp;&amp; sudo apt install /tmp/leaf_latest.deb
</pre><p>Leaf installs tools, images and packages into the <code>~/</code>.leaf/ directory; all configuration is stored in <code>~/</code>.config/leaf/</p>
<p>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 <code>$HOME/myWorkspace</code>.</p>
<pre class="fragment">$ mkdir ~/myWorkspace; cd ~/myWorkspace
</pre><h1><a class="anchor" id="confLeafsearch"></a>
Search for Packages</h1>
<p>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.</p>
<dl class="section warning"><dt>Warning</dt><dd>You are able to search leaf from anywhere on your computer; running <code>leaf</code> <code>setup</code> 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.</dd></dl>
<p><b>leaf</b> <b>search</b> </p>
<p>Using <code>leaf</code> <code>search</code> 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.</p>
<h2><a class="anchor" id="confLeafsearchTarget"></a>
Search for a Target</h2>
<pre class="fragment">$ leaf search -t &lt;target&gt;    (i.e.; leaf search -t wp76xx will bring back all packages for the wp76 target)
</pre><p>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. </p><pre class="fragment">$ 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)
</pre><p>To see exactly what is contained in the package perform a search with a <code>-v</code> 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. </p><pre class="fragment">$ leaf search -t wp76xx -t latest -v  (returns the details of the latest package for the wp76 target)
</pre><p>For details on each of the components of the package visit the vendors page. Firmware Details (including Yocto distribution, toolchain and firmware): <a href="https://source.sierrawireless.com">source.sierrawireless.com</a> Legato Details: <a href="https://legato.io/releases">Releases</a></p>
<h1><a class="anchor" id="confLeafSetup"></a>
Set up Development Environment</h1>
<p>Now that you know which package that you want to install on your development machine, the next step is to run <code>leaf</code> <code>setup</code>. The <code>setup</code> 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.</p>
<pre class="fragment">$ leaf setup &lt;profile name&gt; -p &lt;package identifier&gt;

$ leaf setup wp76stable -p swi-wp76_1.0.0  (downloads and installs the swi-wp76_1.0.0 package in the wp76stable profile)
</pre><dl class="section note"><dt>Note</dt><dd>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.</dd></dl>
<p>After installation a new directory (<code>leaf-data</code>) and a new configuration file (<code>leaf-workspace.json</code>) 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.</p>
<p>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 <a class="el" href="toolsLeaf.html">Leaf</a>. </p><pre class="fragment">$ 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 &lt;profile name&gt;
$ leaf profile rename &lt;old name&gt; &lt;new name&gt; - renames your profile
</pre><h1><a class="anchor" id="confLeafSetup2nd"></a>
Set up a 2nd Profile</h1>
<p>To set up a second profile (if you wish to use multiple targets, or multiple versions) run the <code>leaf</code> <code>setup</code> command again and choose a new profile name. </p><pre class="fragment">$ leaf setup &lt;2nd profile&gt; -p &lt;2nd package identifier&gt;

$ leaf setup wp76dev -p swi-wp76_1.0.0
</pre><p>To see the two profiles set up use <code>leaf</code> <code>status</code> and <code>leaf</code> <code>select</code> to switch between profiles. </p><pre class="fragment">$ leaf status
$ leaf select &lt;profile name&gt;.
</pre><h1><a class="anchor" id="confLeafShell"></a>
Leaf Shell</h1>
<p><code>leaf</code> <code>shell</code> provides an interactive shell that is <b>profile</b> 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.</p>
<dl class="section warning"><dt>Warning</dt><dd><code>shell</code> is $PWD dependant; if you switch to another directory outside of your workspace you will lose your <code>leaf</code> environment variables, and it will not be profile aware (automatically switch to the toolchain and tools that match the profile you are using).</dd></dl>
<p>i.e.; Using <code>mksys</code> 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 <code>mksys</code> again it will use the version configured with the second profile and use the toolchain configured for the second profile environment.</p>
<h1><a class="anchor" id="confLeafWorkspace"></a>
Set up Workspace</h1>
<p>Now that you have all your development environment set up and configured you are now able to start development.</p>
<p>All leaf packages are downloaded to <code>$HOME/</code>.leaf by default (see <code>leaf</code> <code>config</code> to <code>update</code>) and are used as references to be included in to your workspace via environment variables.</p>
<p>Any new environment variables that you would like added to your development environment can be added with <code>leaf</code> <code>env</code>. See <code>leaf</code> <code>help</code> <code>env</code> for details on adding new environment variables to either a profile or a workspace. </p><pre class="fragment">$ leaf env profile --set MYVAR=1  (sets the environment variable MYVAR to 1 for the current profile)
</pre><h1><a class="anchor" id="confLeafDevelopment"></a>
Legato Development</h1>
<p>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 <code>mksys</code> from within the leaf shell in your workspace.</p>
<p>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 GitHub. Use the command <a class="el" href="confLeafSrc.html">leaf getsrc legato</a> to checkout the version of Legato that matches your profile.</p>
<h2><a class="anchor" id="confLeafDevelopmentLegato"></a>
Legato Workflow Changes</h2>
<ul>
<li>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.</li>
<li>You do not need to run <code>bin/legs</code> or source <code>bin/configlegatoenv</code> 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.</li>
<li>Do not add your apps and settings to default.sdef you are now able to <code>#include</code> <code>default.sdef</code> in an sdef in your workspace and build not only your settings but all the default legato apps and configuration.</li>
</ul>
<dl class="section note"><dt>Note</dt><dd>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 <code>leaf</code> <code>help</code> <code>legato-source</code> to download and connect tracked Legato source code.</dd></dl>
<h2><a class="anchor" id="confLeafDevelopmentSDEF"></a>
Set-up SDEF</h2>
<p>Using your own <code></code>.sdef file is easy to set up and maintain. Using this method leaves all the Legato configuration in <code>default.sdef</code> and allows you to quickly see and work with your customization to your Legato System.</p>
<p>Create a new <code></code>.sdef file in your leaf workspace: </p><pre class="fragment">$ vim mySystem.sdef (or the editor of your choice)
</pre><p>In <code>mySystem.sdef</code> use the following line to include all the default Legato settings: </p><pre class="fragment">#include $LEGATO_ROOT/default.sdef
</pre><p>You are also able to include any other <code></code>.sdef files you wish using the same method.</p>
<p>A couple of very useful environment variables that are set up in Legato:</p><ul>
<li><code>$LEGATO_ROOT</code> - resolves to the location of the Legato Application Framework for your profile</li>
<li><code>$CURDIR</code> - resolves to the directory where you run the mktools from (i.e.; add <code>$CURDIR/path/to/your/app</code> to the apps section of your .sdef and then run mksys from your workspace directory to build your apps into the update file)</li>
</ul>
<p>To build your system you no longer need to re-make the build. Run <code>mksys</code> and point it at your <code></code>.sdef. To build a Legato System using your custom sdef run: </p><pre class="fragment">$ mksys -t $LEGATO_TARGET &lt;sdef&gt;   (i.e.; mksys -t wp76xx mySystem.sdef from your leaf workspace directory)
</pre><h2><a class="anchor" id="confLeafDevelopmentWorkspace"></a>
Workspace Layout</h2>
<p>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 <code>$CURDIR</code> to reference the workspace folder in your .sdef.</p>
<p>Example directory structure using the helloWorld app: </p><pre class="fragment">  .
  ├── 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
</pre><p>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.</p>
<h2><a class="anchor" id="confLeafWorkflows"></a>
Workflows</h2>
<p>The Leaf workflow design includes a hierarchy and is set up with the first install of a leaf package:</p><ul>
<li>USER (universal config for all workspace and profiles)</li>
<li>WORKSPACE (the working directory for your code and your customization)</li>
<li>PROFILE (target/version specific configuration and settings)</li>
</ul>
<p>See <a class="el" href="confLeafWS.html">leaf help legato-workflow</a> for more details on the relationship between profiles, workspaces and users.</p>
<p class="copyright">Copyright (C) Sierra Wireless Inc. </p>
</div></div>
<br clear="left"/>
</div>
</div>
<link href="resources/css/jqtree.css" rel="stylesheet" type="text/css"/>
<script src="resources/js/tree.jquery.js" type="text/javascript"></script>
<script src="resources/js/jquery.cookie.js"></script>
<script src="https://code.jquery.com/ui/1.11.4/jquery-ui.min.js"></script>
<link href="resources/css/perfect-scrollbar.min.css" rel="stylesheet"/>
<script src="resources/js/perfect-scrollbar.jquery.min.js"></script>
</body>
</html>
