SAS G-CLI Tools Documentation
Getting Started
About
SAS G-CLI Tools is a set of Open Source G-CLI tools for common LabVIEW Tasks. Each is provided in it's own VIPM package, so you can install just the ones you want. Each G-CLI tool is Open Source and hosted in it's own GitLab repository, so you can fork them and modify them all you want.
Why?
These tools are useful for automating your testing and build process in LabVIEW. Using these tools, you can write a simple bash script to run your unit tests and then if they pass build your executable and package it up. It creates a robust and repeatable process. These types of tools are essential for CI/CD.
Installation
Each of these G-CLI Tools is available on VIPM. That is the easiest way to install them.
Here are the links to download the latest packages from VIPM.
Liscensing
All of the tools are licensed under the MIT license. A license file is included in each VIPM installation package.
Verifying G-CLI Works
You need to make sure that G-CLI is in your PATH. Instructions for that differ based on what shell you are using.
To test G-CLI you can simply do the following:
g-cli echo -- "hello world"
Supported Versions
- LabVIEW -These tools are packaged with VIPM using LabVIEW 2020, so they should work with any LabVIEW bitness, version 2020 or later.
- OS - These tools are Windows only at the moment, although the latest G-CLI apparently also works on Linux, so perhaps that may work. If you try it and find out, please let me know. I'm still on Windows 10, but there is no reason they shouldn't work with Windows 11.
- G-CLI - 2.4.0.4 or later.
Available Commands
-
clearlvcache - A G-CLI tool for clearing the LabVIEW Cache.
-
vipc - A G-CLI tool for applying VIPC files.
-
lvbuildspec - A G-CLI tool for building LabVIEW build specifications.
clearlvcache
Description
This tool clears both the AppBuilder and CompiledObject Caches. I generally use this as one of the first steps in a job, especially if you are running your job in a VM as opposed to a Docker image. It may not be as useful for jobs running in Docker, since presumably each run of the job starts with a fresh slate by spinning up a new container.
NOTE: in G-CLI version 3.0+ this can be replaced with the built in ClearCache command.
Options
This G-CLI Tool has no options. You just call it directly from G-CLI.
Example
# G-CLI options ignored for simplicity.
# it is really this simple.
g-cli clearlvcache
Repository
For more information and to see the source code, check out the repository here: https://gitlab.com/sas-gcli-tools/clearlvcache
vipc
Description
This tool allows you to apply a VI Package Configuration file (vipc) using G-CLI. You point to the vipc file and the version of LabVIEW and this tool will check to see if it needs applied and apply it if necessary.
Options
This G-CLI Tool has the following options:
| flag | parameters | required | description |
|---|---|---|---|
| --lv-version, -v | LabVIEW Version | no | LabVIEW version to install VIPC to. Defaults to internal version of VIPC file. If 64 bit LabVIEW you must specify. Example 22.3 (64-bit). |
| --timeout, -t | VIPM API timeout | no | time to wait for VIPM API timeout. Defaults to 300s |
Example
# G-CLI options ignored for simplicity.
# -- seperates the g-cli options from the options for this specific tool.
g-cli vipc -- -v "22.3 (64-bit)" myvipcfile.vipc # Applies myvipcfile.vipc to LabVIEW 22Q3 64 bit
Repository
For more information and to see the source code, check out the repository here: https://gitlab.com/sas-gcli-tools/vipc
lvbuildspec
Description
This tool allows you to build LabVIEW build specifications using G-CLI. It allows to take advantage of automatic version calculation, manually supply a build number or use the built-in autoincrement functionality. For a description of the auto-increment functionality, see this blog post
Options
This G-CLI Tool has the following options:
| flag | parameters | required | description |
|---|---|---|---|
| --project, --proj, -p | project path | yes | Project containing build specification |
| --buildspec, -b | build spec to build | yes | Specific build specification to build |
| --target, -t | target to build for | no | Target that contains build specification. Defaults to MyComputer |
| --version, -v | version | no | Version number x.x.x.x to assign to build. If left empty just uses whatever is currently set in the LabVIEW Project. --manualversion and -mv also work for backwards compatibility, but are deprecated and will eventually be removed |
Example
# G-CLI options ignored for simplicity.
# -- seperates the g-cli options from the options for this specific tool.
g-cli lvbuildspec -- -p myproject.lvproj -b myexe -v 1.2.3.4 # builds my exe with version number set to 1.2.3.4
Repository
For more information and to see the source code, check out the repository here: https://gitlab.com/sas-gcli-tools/lvbuildspec
Next Steps
This just a section of information to help get up and running with GitLab CI. Why GitLab CI? It's what I use and know. If I'm honest this section is mostly about just documenting my process, but I am hoping that others will find it useful. Towards that goal I tried to make it fairly generic.
Setting up a GitLab Runner
On my blog I have a few post about setting up GitLab Runners. It's spread over a few articles and a little disjointed. I'll attempt summarize it all in one place here.
Assumptions
I'm making a few assumptions here. I am assuming you are using Windows (it should be similar for Win10 or Win11). I'm also going to be setting this up to use Git Bash instead of Powershell. I detest Microsoft and I don't know Powershell, but I do know Bash, so that is what I am going to use. If you want to use Powershell, the initial setup will be a little easier (because that is the default for GitLab shell runners on Windows). However you may have to tweak some of the yaml files and scripts. I am also assuming that you are using VIPM pro or the Community Edition. You need one of those in order for the vipc applier tool to work.
Starting Point
As a runner you will want a seperate machine from your dev machine. This could be a spare laptop or desktop, a VM running on your own desktop or server or a VPS running on something like Amazon, Vultr, or Digital Ocean. You'll need just enough horsepower to load your project and run a build. It will need access out to the internet to be able to ping gitlab.com (or if you are self-hosting, then whatever your url is for your GitLab server). You should consider keeping it on a seperate network isolated from your main network, because running a build basically opens up a reverse shell.
Access to Runner Machine
You will want to be able to logon to the runner and view the GUI for setup/installation and troubleshooting. For a physical machine that should be easy. RDP works best for remote machines, but VNC, MSP360 or Team Viewer will also work. Don't expose RDP or VNC to the internet. It is not secure. Run it through some encrypted tunnel like ssh, a vpn, wireguard, Nebula, etc.
Initial Software Installation
I'm assuming you are using Windows, so you will want to install the appropriate Windows Version and turn on Remote Desktop (if that is what you are using for access) You will want to install Git For Windows along with Git Bash. The default options should be fine. You will want to install NIPM and use that to install the proper version of LabVIEW, VIPM, DAQmx and any other drivers you need. You'll also want to install some basic VIPM packages such as G-CLI and the VIPM API. You'll also want to install whatever of the SAS-GCLI tools you want to use. If you have the Pro or Community edition of VIPM, then you can use the vipc applier tool to install packages as part of your CI pipeline. If you aren't doing that, then you should probably install the needed packages now. If you are using Python to run any build scripts or utilities, now is a good time to install that and any needed Python packages as well.
You really don't want to install a lot of extras. You are not going to be using this machine for anything other than running builds. Running a build basically opens up a reverse shell, so you don't want anything sensitive on there other than your code.
Initial Verification
You should manually open VIPM and LabVIEW and make sure no licensing dialogs pop up and take care of them if they do. You should verify that VIPM can connect to your version of LabVIEW by opening VIPM and going to the settings dialog box. You should also verify G-CLI is installed correctly and can connect to LabVIEW by typing g-cli echo -- "Hello World" into Git Bash and verifying that it returns "Hello World". If it doesn't, check your $PATH and make sure it contains the G-CLI directory. You may need to add an export line to your .bashrc file.
Installing GitLab Runner
The instructions for installing the gitlab-runner program provided by GitLab are pretty good. Make sure you select shell as your executor when it asks. You should just follow up until the point where it tells you to install it as a service. If you want to be able to actively debug and watch what is going on, you don't want to do this. So stop after step 5 and don't proceed to step 6.
Setting up GitLab Runner to use Git Bash Instead of PowerShell
NOTE: This section describes how to set up GitLab Runner to use Git Bash. If you want to use PowerShell you can skip this.
First, we need to help GitLab Runner find GitBash. Add a bash.cmd file into your user directory (the user that runs the GitLab Runner) with the following contents:
@"C:\Program Files\Git\usr\bin\bash.exe" -l
Next, we have to make sure that our starting paths are set up correctly with Linux-style formatting. In your config.toml file for your GitLab runner (it’s in the directory where you installed GitLab Runner), change the shell to bash and add Linux style paths for the builds_dir and cache_dir. That’s it. See the example below.
[[runners]]
name = "windows"
url = "https://your.server.name"
token = "YOUR_SECRET_TOKEN"
executor = "shell"
shell = "bash"
builds_dir="/c/gitlab-runner/builds/"
cache_dir="/c/gitlab-runner/cache/"
NOTE on Paths: We are using linux paths here, but when passing paths as parameters to the g-cli tools (ie the parameters after the -- ) you will need to use Windows Paths.
Running as a User
Create the following batch file with the following line in it.
`"C:\Program Files\Git\bin\sh.exe" --login -i -c "cd /c/Gitlab-Runner && ./gitlab-runner.exe run"'
Save it somewhere convenient, like the Desktop and give it a meaningful name like "Start GitLab Runner.bat" Running this batch file will open a console window as seen below. Once a job starts, then you’ll see all the windows that it opens. You’ll see the LabVIEW splash screen and any VIs it opens. So if it hangs on some dialog, you will know about it.
Set to run at Startup
In order to run the script at startup (when the current user logs in), drop a link to into the Windows Startup Folder. You can find the Windows startup folder by hitting the windows key + R and typing shell:startup into the resulting dialog box.
Setting User to Autologon
The last thing I typically do is set the user to autologon, otherwise every time the machine boots up, you have to login to the machine before gitlab-runner can start. The way to do that in windows is to use netplwiz. Hit windows key + R and type in netplwiz. It will open a User Accounts window. You should see a checkbox at the top that says "Users must enter a user name and password to use this computer." Simply uncheck it.
NOTE: You may not see that checkbox. If you don't you can try adding a registry key. Copy the code below. Open a command prompt as administrator. Paste and run the code. Reboot. The box should show up now. If not, there are some other potential fixes, just google it.
reg ADD “HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\PasswordLess\Device” /v DevicePasswordLessBuildVersion /t REG_DWORD /d 0 /f
Success!
Once you have done all the above steps, your runner should be good to go.
Example GitLab YAML files
COMING SOON - I hope to add example .gitlab-ci.yaml files for both LabVIEW built executables and NIPM packages and also for VIPM packages for reuse code. I'm working on getting the other tools done first though.
The idea is that you could potentially copy these into your project, change a few variables and be ready to go with CI in a matter of minutes (assuming you already have the runner setup and assigned to your project).
For an Executable and NIPM Package
For a VIPM Package
Example Python Script
COMING SOON - I hope to put up a Python script for building. The idea being to simplify the yaml file by having it just call the python script that way you can just run the python script locally and get the same output.