Overview

The main power of Content Server comes from its modular architecture, provided by a self-contained units called modules. Content Server allows the users to extend and customize the framework by developing their own modules without the need to modify the code in any other module.

Building an OScript module has always been done through GUI tools, either CSIDE or the legacy Builder. With the advance of build automation and CI/CD, the need arose for a CLI tool that can build OScript projects and easily integrate with build automation systems like Jenkins and Teamcity. OBuild is the first tool in our vision for a set of CLI tools to enrich the OScript SDK.

Setup and Installation

Prerequisites

• Content Server (OTHOME)

OBuild uses existing content server installation (i.e, OTHOME) on the same machine to build your project similar to CSIDE. If you can build your module/project using CSIDE then you can easily use OBuild to automate your module build process. Any dependency that your module requires, must be properly installed in OTHOME. You need to ensure that the user that runs OBuild has write access to OTHOME similar to CSIDE.

However, unlike CSIDE, OBuild will not be updating the built OSpaces in your OTHOME. It will produce the built OSpaces and Weblingo files into a distribution folder specified as command line argument as will be discussed in the coming section. It is your decision what and when OTHOME modules should be updated.

• Java runtime

OBuild is Java based application so you need to have Java runtime installed on your system. Minimum recommended version is Java 11 .

Add OBuild to PATH

OBuild is distributed as a zipped package. You need to extract the content of the package to a directory, for example, C:\obuild on Windows, or /usr/local/obuild on Linux. You need to copy the contents of the package over to the installation. On Linux, you may also find it easier to copy the tool to a local directory on the user home directory and add that location to the Path. Note that the user executing the script will need to have write permissions to OTHOME directory as OBuild needs to create some files there.

you need to add this directory to your PATH so you can invoke OBuild from any location. On Windows,

Content server installation (OTHOME)

OBuild uses existing Content Server installation (i.e, OTHOME) on the same machine to build your project similar to CSIDE. If you can build your module/project using CSIDE, then you can easily use OBuild to automate your module build process. In other words, Any dependency that your module requires, it is your responsibility to make sure it is properly installed in OTHOME.

However, unlike CSIDE OBuild does not update the built OSpaces in your OTHOME. It will produce the built OSpaces and Weblingo files into a distribution folder specified as a command line argument, as will be discussed in the coming section. It is your decision what and when OTHOME modules should be updated.

Running OBuild

To check your installation, run obuild -h. The output should list the help as shown.

OBuild command options

Running OBuild shows the available options and their usage. In this section we describe each of these options as a use case for building an OScript module. The help message is displayed when the -h or --HELP option is provided to the OBuild call.

As shown, it displays the version of OBuild, for example 22.4.0.v20220913_02529. You can also check the version using the command line argument --VERSION. Similar to CSIDE, OBuild should be backward compatible to versions of Content Server back to 10.5. To be clear, if you can run CSIDE against that Content Server, you will probably be able to run OBuild smoothly.

Running OBuild with actual arguments to build a set of modules is shown below. Next we discuss each field.

--OTHOME

This is a mandatory argument that represents the path for the directory where you set up Content Server. It can be specified as an absolute Path or relative Path. This is the main component in the build process. This directory contains all the modules, OSpaces, built-ins, Xlates strings, and Weblingo files you reference in your builds. Basically, you can look at this as the SDK version you build against. As an example, if you have Content Server 22.3 installed in directory cs223, and Content Server 22.4 installed in directory cs224. If the module you build is referencing a feature in a module like Active View, that existed in 22.3 and was removed in 22.4, your build will basically succeed when you set OTHOME to cs223, and will break when OTHOME is set to cs224.

You need to make sure you also install any dependencies your module needs in that OTHOME. If you can build using CSIDE on this OTHOME then you can use it for OBuild

The argument can be specified using the short form -ot, or the long form --OTHOME. The directory must contain a working installation of Content Server or you will have broken builds and serious errors.

obuild_startup.lxe

--SRCFOLDER

This mandatory argument represents the Path to the workspace source folder that contains the OScript source Modules to be built. This is similar to the srcmodules created in CSIDE workspaces that contain folders where each folder represents a module. The current implementation assumes the source folder is a set of modules. Any file or directory that is not a module is ignored during the build with a warning message.

The module folder is identified by the module.ini. The file name should be the module folder name. OBuild also supports the folder name with encoded version number like restrictedcategories_16_5_3. Folder naming and the ini file content are not a concern as long as you used what CSIDE already generated for you.

The module contains number of OSpaces. Usually not all OSpaces are meant to be distributed, for example, unit test OSpaces. Usually the OSpaces to be distributed are recorded in the ini file. We provide all the included ospaces, so you have the option to remove extra ospaces from the distribution package as appropriate.

Besides OSpaces, the module contains help and support folders with a number of Weblingo files and resources like css, JavaScript, media files, and others. We build the Weblingo files and copy over the resources as appropriate to the distribution package in the output directory.

--DSTDIR

This optional argument specify the destination directory (or the output directory) where the built items are written. If not specified, OBuild will use the current directory as the destination folder. Unlike CSIDE, OBuild produces the new OLLs and Weblingo files in the destination directory. It will not modify the version installed in OTHOME, if it exists.

The destination directory contains a log file for each run for OBuild, where the file name is the build ID which is generated based on the date and time of the build to ensure its uniqueness. The logs contain the OScript thread log output that is usually displayed on the CSIDE console and the OBuild tool log lines that usually will be preceded with the word OBUILD.

Aside from the log a directory is created named staging to honor the convention used in Content Server where new modules to be installed are placed in the staging directory in OTHOME. The figure below shows the out directory for OBuild running a source workspace containing two modules channel and bestbets

The folder listing shows that five log files exist in the directory, which means OBuild ran five times using that directory as the destination directory. The staging directory was overwritten in each run. The tree listing shows what the staging directory contains. Each module has a separate directory that contains the module ini file and ospace directory that contains all the built OSpaces. Moreover, all Weblingo and support folders are copied over with the included resources after being properly processed. As shown for the channel module

The figure below shows the channel module.

Exit code

The exit code is how OBuild communicates the build status to the caller. As per standard CLI tool, OBuild returns 0 in case of build success. A build is successful if it has no errors even it contains a number of warnings. A failed build with exit code 500 means that build errors occurred. The error message is printed besides the exit code value (in case of not 0). You can see a summary line containing the number of errors and warnings OBUILD INFO Build failed with 5 errors, 18 warnings. The full log is located in the output folder named with the generated build ID. In the example below example it is C:\workspace\obuild\out\build1664408270092.log .

With a successfull build, a return value of 0 is expected with the message printed as OBUILD INFO Build successfully with 0 errors, 74 warnings. This is taken from successfull build of the same code, but against a different OTHOME.

A summary of current exit codes and their meaning:

OBuild logs

Getting the logs is the first step to understand what went wrong. OBuild has two logs. One is a generic log that is located in the user profile folder under C:\Users\userx\.opentextsdk\obuild\logs for userx on a Windows, while when userx is building using Linux, it will be located at /home/userx . Note that directories starting with . on Linux are hidden.

--VERBOSE

Feedback