A Tool for 4D Code Execution in CLI

In the development industry, CI/CD has become a standard practice. With each code modification, automated actions such as testing, compilation, building, delivery, and sometimes deployment are generated to ensure the code is high quality and easily integrated into the existing system.

These actions require a tool to execute the necessary code. As 4D developers, we decided to provide a free tool that allows developers to execute elementary actions. This tool is called tool4d, and it streamlines the process of executing necessary actions within the 4D environment.

In this article, we will explore the functionalities of tool4d and how it can be used to enhance your development process.

This new application is mainly dedicated to being integrated into CI/CD pipelines. The main goal of tool4d is, therefore, to execute 4D code with a minimal instruction set, a minimal memory footprint, and a minimum size. The tool4d application can be seen as a subset of the 4D application.

How does it work?

First, tool4d is released like 4D, so they share the same version and build number.
Even though the tool4d is displayed with its icon, the application can only be run via Command Line Interface.
Its execution is always done in headless mode. To feed back information, you can use the stdout stream, even on Windows, as follows:

LOG EVENT(Into system standard outputs; “message”)

The following sequence of methods is always executed:
1. tool4d executes the On Startup database method, except if the –skip-onstartup parameter is defined.
2. tool4d executes the method designated by the –startup-method parameter if defined.
3. tool4d executes the On Exit database method, except if the –skip-onstartup parameter is defined.
4. tool4d exits.

To make tool4d as light as possible, many elements of 4D have been disabled, such as the Application server, Web server, SQL Server, backup scheduler, and so on.
And last but not least, tool4d does not need any license to run.
You can find more details in the documentation.

How to get it?

The tool4d applications are available on the Product Download portal for three system targets: Windows, macOS Intel, and macOS Silicon.
As tool4d is free and can be used in CI/CD pipelines, you can get it without authentication under the https://resources-downloads.4d.com with the exact query string for Product Downloads.
For example, the latest v20 LTS versions can be downloaded directly with these links:

https://resources-download.4d.com/release/20.x/20.0/latest/mac/tool4d_v20.0_mac_arm.tar.xz
https://resources-download.4d.com/release/20.x/20.0/latest/mac/tool4d_v20.0_mac_x86.tar.xz
https://resources-download.4d.com/release/20.x/20.0/latest/win/tool4d_v20.0_win.tar.xz

The packages are compressed with the tar.xz algorithm, guaranteeing a minimal file size. If no application compatible with this format is installed in your system, you can decompress the package using the following command lines.

Windows:
tar xvzf {tool4dCompressedFile} -C {destinationFolder}

macOS:
tar xvzf {tool4dCompressedFile}

UseCases

There are many use cases for tool4d. Here are some of them, but we let you imagine many other use cases!

Compilation

tool4d is very suitable for building tasks such as unit tests or compilations. Here is an example of a small project named compileThisProject compiling another project.
The compileThisProject project gets a project file path, compile it, and then displays the compilation result in the terminal. Its “On Startup” database method contains this code:

LOG EVENT(Into system standard outputs; "Compilation starts\r\n")
var $projectPath : Text
var $result : Integer
var $compilationReturn : Object

// Getting the string value of the --user-param parameter in the CLI
$result:=Get database parameter(User param value; $projectPath)
If ($projectPath#"")
	$compilationReturn:=Compile project(File($projectPath))
	LOG EVENT(Into system standard outputs; "Compilation returns:\r\n"+JSON Stringify($compilationReturn; *))
End if 

The command line to execute:

/Applications/tool4d.app/Contents/MacOS/tool4d --project "/Users/Me/compileThisProject/Project/compileThisProject.4DProject" --user-param "/Users/Me/Test/Project/Test.4DProject"

And here is the result:

Compilation starts
Compilation returns:
{
 "success": true,
 "errors": []
}


Continuous Integration

The compilation is one step in CI/CD pipelines. Whatever your CI/CD platform, you can use tool4d for each step!
We already talked about GitHub Actions in this blog post. It’s a GitHub platform that allows you to automatically run actions on GitHub events like pushing code or merging a pull request. And these actions can be run on macOS or Windows virtual machines.
Here is a sample of a YAML script for GitHub Actions that run unit tests on each code push on GitHub:

name: Unit Tests
on:
  push:
    branches: [ "main" ]
jobs:
  Unit-tests-on-windows:
    name: Unit Tests on Windows
    runs-on: windows-latest
    permissions: write-all
    steps:
      - uses: actions/checkout@v3
      - name: "Download latest tool4d release and expand"
        run: |
          curl https://resources-download.4d.com/release/20.x/20.0/latest/win/tool4d_v20.0_win.tar.xz -o tool4d.tar.xz -sL           tar xvJf tool4d.tar.xz -C tool4d
      - name: "Run Unit Tests"
        run: |
          ./tool4d/tool4d.exe --project ${{ github.workspace }}\Project\myProject.4DProject --dataless --skip-onstartup --startup-method "runUnitTests"
  Unit-tests-on-macos:
    name: Unit Tests on macOS
    needs: [Unit-tests-on-windows]
    runs-on: macOS-latest
    permissions: write-all
    steps:
      - uses: actions/checkout@v3
      - name: "Download latest tool4d release and expand"
        run: |
          curl https://resources-download.4d.com/release/20.x/20.0/latest/mac/tool4d_v20.0_mac_x86.tar.xz -o tool4d.tar.xz -sL           tar xvzf tool4d.tar.xz
      - name: "Run Project Unit Tests"
        run: |
          ./tool4d.app/Contents/MacOS/tool4d --project ${{ github.workspace }}/Project/myProject.4DProject --dataless --skip-onstartup --startup-method "runUnitTests"

Note that tool4d needs no license to run, so there’s no need to register anything in the virtual machines! 

Maintenance

You can also use tool4d for maintenance tasks. For example, if you want to verify a 4D Server data file and ensure no user connects to the server. Note that for this use, you can also use the 4D Server application with the “—utility” parameter: it will execute the same sequence of methods as tool4d.

Command line to do that:
/Applications/4D/4D\ Server.app/Contents/MacOS/4D\ Server --utility --project “{pathToProjectFile}“ --skip-onstartup --startup-method “verifyDataFile”

The verifyDataFile method contains a call to the VERIFY CURRENT DATA FILE command.

 

Hope that tool4d will help you in your CI/CD pipeline design and other tasks!

We constantly strive to provide our users with the best possible experience, and we encourage you to share your thoughts and feedback on the 4D forum. Your feedback helps us better understand your needs and continuously improve our products and services.