Installation

There are two components required for G-CLI:

• The G-CLI proxy application which is launched from the command line.
• The G-CLI library which must be installed to each LabVIEW version.

G-CLI Library

The G-CLI library is available through VIPM.

1. Launch VIPM.
2. Search for G-CLI
3. Install for each version of LabVIEW you need.

Alternative releases will be listed at https://github.com/JamesMc86/G-CLI/releases.

G-CLI Proxy

On Windows this is installed by VIPM at the same time as the library.

On Linux you need to download a package from the github releases page at https://github.com/JamesMc86/G-CLI/releases.

Post Install

On Windows G-CLI must be added to the path so you must restart any terminals or build agents after the first install to include the new path variable.

Getting Started

Basics

G CLI is a command line tool which communicates with a special library in your LabVIEW application or VI in order to add the ability to return standard output and exit codes which is very difficult or impossible otherwise.

VI Setup

The VI you call should:

1. Have the G CLI library included to initiate the connection to the command line and communicate back to it. This is a very simple API with a connect, write and exit (with exit code) pattern.
   

2. Be set up to run on launch (if being run as a VI, not an executable).

As this suggests you can use this to call VIs in the LabVIEW environment OR once built into an executable.

Launching a VI

Before launching a VI you should ensure LabVIEW will launch without any dialogs. The best thing is to open the VI manually and see if any dialogs come up. Examples are missing VIs or licensing dialogs. These will stop LabVIEW from running your code and must be corrected first.

To launch a VI in LabVIEW 2014 you then enter the command g-cli --lv-ver 2014 "C:\nameofvi.vi". For the 64 bit version add the --x64 flag e.g. g-cli --lv-ver 2014 --x64 "C:\nameofvi.vi"

To launch a VI which has been built into an executable you can just provide the exe path e.g. g-cli "C:\nameofvi.exe". The program will detect the .exe extension and launch it directly (note: there was a bug in this in at least v1.4-v1.5. Update to v1.5.1 to use this mode).

If you want to provide your own command line parameters to your VI place them after a -- e.g. g-cli --lv-ver 2014 "C:\nameofvi.vi" -- "parameter 1" "parameter 2". The quote marks tell Windows to ignore the spaces so it doesn't generate 4 parameters.

Demo

There is an example VI that ships with the tool for you to try it out. To launch it call:

g-cli --lv-ver <LABVIEW_VERSION> "<LABVIEW_DIR>\examples\Wiresmith Technology\G CLI\CLI Demo.vi" -- "demo 1" "demo 2"

Then run the VI when it launches. This does not have auto-run set intentionally so you can see what happens if the code doesn't run (the interface times out) and can easily inspect the code.

Full Command Line Interface

The command line contains a number of settings you can use for more advanced features:

g-cli [options] launch-vi [-- application arguments]

last argument (or last before -- if user arguments) is what to launch. This can be a local VI, LabVIEW build executable or it will search in "<vi.lib>\G" CLI Tools for a matching tool.

Basic Flags

Any arguments after -- are passed to the application.

Advanced Usage

Platform Considerations

Linux

On Linux return codes are in the range of 0-255. Setting exit codes outside of this range will result in exit codes that don't match what is set in LabVIEW.

Continuous Integration or Headless Usage

A major use case for this toolkit is in continuous integration systems. This toolkit is intentionally simple and does not include any specific steps to allow developers to create their own tools. If you are interested in this you can use the following tools from the web:

• LabVIEW CLI Common Steps. Github: https://github.com/LabVIEW-DCAF/buildsystem/.
• Command Line Tools for LabVIEW. Github: https://github.com/chinghwayu/Command-Line-Tools

It has been successfully used with Jenkins and Gitlab CI and should support any CI tool that can call to the Windows command line.

Powershell Usage

Powershell does not automatically detect non-zero error codes or standard error outputs as a failure and so some build systems may show the script as passing even after G-CLI reports an error. This is a specific design of powershell and is referred to as a non-terminating error.

For this reason try/catch blocks will not work with these either.

The best recommendation is to check the $? variable such as:

if(!$?) { Exit $LASTEXITCODE }

Some tools, such as Gitlab, insert these automatically after your commands (see https://docs.gitlab.com/runner/shells/)

Avoiding LabVIEW Dialogs

LabVIEW dialogs will halt a headless system and make it appear to hang - resulting in a connection timeout error.

Since version 2.2 we set the unattended flag which should prevent dialogs from appearing and blocking the execution of our VIs.

However there are still two instances (at least) that I see.

1. Activation Dialog

I don't know there is anything that can be done for this.

2. Recovery Dialog

If LabVIEW crashes with unsaved changes the recovery dialog may show still. This has been reported as a bug.

You can disable this in the options of the LabVIEW install though. See https://knowledge.ni.com/KnowledgeArticleDetails?id=kA03q000000x1g6CAA&l=en-GB

Configuring your build agent to show a UI

By default, build agents run as a service. However this means that they run without a user interface which can make it hard to debug.

The following instructions are used at Wiresmith Technology to make the UI visible. However they come with a significant side effect - the user needs to auto-login so anyone with access to the PC is logged in as that user and they can access the password of that user.

1. To limit the security exposure, create a user to run the build server.
2. Use this tool to configure the new user to log on automatically.
3. Download/Create your build agent. This process depends on the build server you are using but we want to end up with the agent executable and the command used to call it. Do not install it as a service.
4. Create a scheduled task in Windows to run the agent. Set it to run after login. Make sure to disable the timeout "stop the task if it runs longer than"

Now when a build runs you should be able to see LabVIEW running.

Tools That Work With G CLI

This page is intended to be a directory of the tools that have been created to work with G CLI, primarily for continuous integration.

Shipping with G CLI

Echo

Echos back any parameters you enter. Useful for testing the setup and install for a given LabVIEW version.

Example: g-cli --lv-ver 2011 echo -- one two three

Quit LabVIEW

Quits LabVIEW that is open. Maybe useful to control in a script when LabVIEW is closed.

Optional parameter -delay which specifies a time delay in ms. Default is 1000ms.

Example: g-cli --lv-ver 2011 quitLabVIEW -- -delay 500

Clear Cache (from v3.0)

Clears the compiled object caches in LabVIEW.

Optionally pass --user-only for only the user compiled cache or --app-builder-only for just the app builder cache.

Example: g-cli --lv-ver 2011 ClearCache -- --user-only

From the G CLI Project

These tools are developed by the same people as G CLI and are all open source. Check the release section under code for the latest version.

• LabVIEW Builder - lvBuild - https://github.com/JamesMc86/G-CLI-lvBuild
• VI Package Manager Interface - https://github.com/JamesMc86/G-CLI-VI-Package-API
• VI Tester Runner - https://github.com/JamesMc86/G-CLI-VI-Tester-Runner

Other open source projects powered by G CLI

• Caraya-CLI-extension - Github
• CLI for Antidoc - Gitlab / VIPM
• CLI for DQMH modules validation - Gitlab / VIPM

Commercial Tools

• Release Automation Tools from Hampel Software Engineering provides CI/CD tools that are powered by G CLI - https://rat.hampel-soft.com

Legacy

The follow repos absolutely work, but they don't take advantage of the search integration within G CLI.

• LabVIEW CLI Common Steps. Github: https://github.com/LabVIEW-DCAF/buildsystem/.
• Command Line Tools for LabVIEW. Github: https://github.com/chinghwayu/Command-Line-Tools

Troubleshooting

This page captures some common failures.

Often the answer is to get it to run with a GUI and see what is going on.

Connection Timed Out

• Make sure there are no save dialogues from a previous run of LabVIEW. (shouldn't occur after v2.2.0)
• Check you can open and run LabVIEW without licensing or recovery dialogues?
• Does your code open broken on the system you are trying to run it on?
• Does your code have to search for a long time for dependencies?

Creating Tools Process

Code and VI Setup

First, create a VI that does what you want using the CLI library. Avoid dialogs or dependency on UIs.

Then ensure it runs when opened in VI properties.

Finally consider what happens when it ends. Options are:

• Nothing - just leave it open. Generally no harm in this if it is for a server.
• Close the VI - This should get you back to the LabVIEW splash screen. This seems to make the most sense as long as you aren't scripting changes that might cause save dialogs. (EDIT: This can also trigger a save dialog if an upgraded G CLI causes a recompile, think nothing might be better)
• Exit LabVIEW - Generally discouraged in CI use cases as it wastes time relaunching LabVIEW.

Setup Installer

This step is if you want the ability for G CLI to find it automatically in it's search path.

• Create a VIPB using VI package manager and enter all your details for the product.
• Create a new destination called G CLI Tools. Set the base path to \vi.lib and make the subdirectory "G CLI Tools". You can add your own subdirectory as well. So if your tool is called "tool.vi" and you have it under "G CLI Tools\wiresmith" it can be called with "wiresmith\tool". This may make sense for a full set of tools.
• Go to source file settings. Set your tool VIs to the G CLI Tools destination. Other VIs can remain in their own directory.
• Be sure to include G CLI as a dependent package along with any other dependencies so this becomes a one-shot install.
• Build and install the package.

Testing

Install your package and run G CLI with the name of your VI (it works even without the extension) - it should run successfully.

LabVIEW Library

The LabVIEW interface library allows you to communicate with the command-line interface that launched the VI.

Start CLI Interface

This establishes the connection back to the command line and provides you with the working directory of the command line and any parameters provided to the VI.

Write String

Writes the text back to the stdout of the command line. Note: you have to include your own new line characters.

Path From Parameter

Takes the working directory and a parameter which represents a file and converts it to an absolute path for access.

Exit With Code

Close the connection to the command line and force the command line application to exit with the code provided.

Exit with Error Cluster Code

Like Exit With Code but instead, this will inspect the error cluster and if there is an error, output a text description and exit the command line with the error code.

Options Parser Library

There is a library included for parsing options from the CLI. Note - there is also a new library which I have yet to evaluate and compare at https://www.vipm.io/package/sklein_lib_lv_argparse/ which may suit your needs better. The options parser enables you to create more complex interfaces with optional parameters to make it easier to use in simple cases.

For example if we have an interface like:

-v -lv-ver 2014 myproject mytarget

We would say that -v and -lv-ver are option labels and 2014 is the value for the -lv-ver option label. myproject and mytarget are trailing arguments.

API

Create Option Set

This VI initialises the options set ready to parse what is sent to your application. You need to specify the options you support through the input array. In each cluster you can set:

• Option type - a flag means there is no associated value e.g. -v for verbose. A value means there is a value to parse afterwards e.g. -lv-ver 2014.
• Option Labels - An array of the labels that are associated with the option on the command line. For example the verbose option might respond to "v" or "verbose".
• Key - The name you will use to access this option once parsed.
• Description - A help text description for the option. Right now this is unused but useful for generating help responses (which we hope to support in the future).
• Required - If this is set to required, the parser will flag if this is missing.
• Default Value - The default used if this isn't set.

Parse Arguments

Pass this the options set and the arguments from the command line in order to parse out the different options you used above.

You can access the options later through the option set object. This will flag if required options are missing at this point.

You can change the label marker input to change how the options are detected. This is a regex input so you can get creative but for ease of use I would recommend sticking to the default -.

Get Option Value

Use this to access the value for a given option after you have parsed the input.

The key is the key you specified in when configuring the option set. You will get the string value back for that option (which will be the default if un-set) and you can detect if the user actually specified this option (the set output).

Get Trailing Arguments

This returns an array of all arguments that weren't associated with an option flag during parsing. Commonly these are the key required elements of your API.

For version 2.0 we change the library name from LabVIEW CLI to G CLI to avoid confusion with NI's tool that they released.

In changing the name there are a couple of points at which things may break. This document outlines those and I ask you report any additional problems you may find.

VI Package

Since the VI package name has changed VIPM will not recognised the upgrade. You will need to uninstall the old package and install the new package manually.

Code Linking

The folder containing the code has changed from <vi.lib>/Wiresmith Technology/LabVIEW CLI to <vi.lib>/Wiresmith Technology/G CLI. Since all functions are contained within the CLI.lvclass you should only need to relink to this. I would advise mass compiling your code which calls to the CLI to fix the links.

Command Line Command

The new tool is now called g-cli to be called from the command line. However it will continue to work with labview-cli. For new scripts though I recommend moving to g-cli in case we have to remove the labview-cli link in the future.

You may need to restart any CI tools or other callers so they recognise the change in the path variables.

This page is an easy way to track and share the expected breaking changes as part of version 3.0.

v3.0 New Features

• Standard Error output is now available in write functions.
• ClearCache tool included in the install.
• Support for packed libraries and LLBs.

System Requirements

These are mostly driven by moving the g-cli tool to Rust for cross platform compatibility.

Mostly, there are just about modernising the minimum requirements and I don't expect a large knock-on affect.

1. 64 Bit OS Only - The tool will still work with 32 bit LabVIEW but the underlying operating system will have to be 64 bit.
2. Minimum LabVIEW version of 2015 (from 2011). This represents a similar age from the original release and I expect covers most users. It allows the use of VI Tester reporting in the CI toolchain which is currently limited to 2013.

Tool Interface

Output Changes

I want to use this as a opportunity to hide all G-CLI output by default. This has been requested before and seems like a sensible request. A major version change seems a good time to introduce it.

• Default output - only errors.
• -v flag - verbose output - current verbose.

Deprecate Timeout

The --timeout flag is now ambiguous with --kill-timeout. This will be deprecated in favour of a --connect-timeout flag.

Deprecate labview-cli shim

The shim to still allow the old name to be removed.

Deprecate No Launch

Its unclear what the use of this is now. All use cases I can think of would launch the app and this increases the software complexity so unless there are significant requirements this will be deprecated as well.

Deprecate/Alter 64 bit flag

Right now we set --x64 to request 64 bit but this not clear by its absence. This flag will continue to work but we will add a new flag for --arch 64 or --arch 32. No flags will default to 32 bit to maintain current behaviour.

StdErr Output

The default case for the write functions is still to use StdOut.

However Exit with Error Code will now write the error message to StdErr. This could lead to errors being shown for the command where they weren't before.