Helium Shared Libraries

Table of Contents

Introduction

The purpose of this article is to provide an example of using the Helium shared libraries feature. 

The source code of most Helium releases can be imported for a DSL app by specifying the libraries to import as part of the app source code and using the repo and fetch-libs commands. When importing with fetch-libs the files are simply imported into the developers workspace which will be bundled into the built application when using the build, run or release commands.

Releasing a Library

As mentioned, most normal app releases can be used as a library. One specific requirement for releases that are to be used as libraries is that a web-app folder is included in the library. It is, however, also good practice to not import the source code for stand-alone DSL apps as libraries. Conventions, such as proper naming of releases, should be followed to make a clear distinction between releases representing libraries and releases representing stand-alone apps. Proper naming conventions should also be used to indicate the versioning of libraries.

As a summary of how to perform a release:

1. Set up your HeliumDev client config to an instance of Helium and a DSL project with valid project directory.
2. Use the release command to publish the source code. Take note of the name you entered for the release as this will be needed to import the release as a library.

For more details and general instruction on how to make use of the HeliumDev client please consult the documentation located here.

Importing Libraries Into a DSL App

Specifying Releases to Import

In order to specify which releases should be imported into a DSL project, the libraries to import should be listed, by name, in a newly introduced shared-lib.list file. This file should be located in the project root folder. The file may contain multiple lines with each representing a library to import:

helium-shared-lib-v1
generic-validation-lib-v1
generic-string-manipulation-lib-v1

Importing Libraries Using the HeliumDev Client

Once the libraries to import has been specified they can be imported using the repo and fetch-libs commands in the HeliumDev client. The following HeliumDev client commands are relevant for shared libraries:

For the example shared-lib.list file as shown in the previous section using the fetch-libs command will result in an attempt by the HeliumDev client to download the contents of three helium releases into the current workspace. If any of the releases can't be found on the repo an error will be thrown on the fetch-libs command.

In summary, the following steps can be followed to import a library into your local workspace for an app:

1. Create an empty file called shared-lib.list in the root of the child project.
2. Use the repo command using the name of the target server in your local HeliumDev client config as the value. Note that the value set when using the repo command is not validated against available server names in your HeliumDev config. If an incorrect value is set here, an error will only be generated during step 4 as discussed below.
3. Update shared-lib.list to include the name of the release you wish to include as a library.
4. Use the fetch-libs command to download the source code of the specified libs. This step will fail if step 2 was note completed or if an incorrect server name was set for the repo.
5. (Optional) Use the purge-libs command at any time to remove all locally imported library files from disk.

Directory Structures Resulting From a Library Import

The following example demonstrates the directory structure of a simple library being imported. Note how the imported library contents are located in the shared-libs folder.

Using an Imported Library

Once a library has been imported into the local directory it can be used as though it is a normal part of the app source code:

// In this example exampleFunctionWithParam is a function that exists 
// in the unit HeliumSharedLibUtil found in a shared library.
HeliumSharedLibUtil:exampleFunctionWithParam("Hello World");

The example above only shows the usage of a method provided. Any source files or resource that can be specified in a DSL app can be provided through a shared library. This includes images, lang files, views presenters and models.

Images

Images found in the web-app/images directory of the release being imported as a library will be made available in the importing project. An image cannot be with the same name cannot exist in both the web-app/images of the main or library project.

Lang Entries

Lang entries found in the web-app/lang directory of a project being imported as a library will be made available to in the importing project. Lang entries imported from a library will be overridden by any lang entries found with the same key in the importing project if the lang files have the same name.

Naming Standards to Avoid Compiler Issues

When a project is imported as a library it is included as regular DSL source code, this means it needs to be able to compile alongside all existing source code in the project. Therefore one cannot import objects, persistent objects, views or presenters from a library if there also exists a resource declared with the same name. While images and lang entries can be overridden, objects, persistent objects, views and presenters cannot. 

Consider the example:

If a project being used as a library declares a persistent object called Farmer, this library cannot be used inside a project that declares a persistent object called Farmer. The library can be imported with the fetch-libs command, but will fail to compile.

To use shared libraries successfully the developer must carefully decide on meaningful naming conventions to allow multiple projects to be integrated together seamlessly. As with the helium-shared-lib example above, units, objects and lang entry keys are prefixed to be unique:

heliumsharedlib.view.title.Helium_Shared_Lib=View in helium-shared-lib

unit HeliumSharedLibUtil;