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.
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.
OBuild is Java based application so you need to have Java runtime installed on your system. Minimum recommended version is Java 11 .
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,
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 will not be updating the built OSpaces at your OTHOME. It will produces the built OSpaces and Weblingo files into 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.
To check your installation run obuild -h
. The output should be listing the help as shown.
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.
This is a mandatory argument that represents the path for the directory where you setup the 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.
ide_startup.lxe
.
This is an advanced topic for CSIDE, so do not worry if you are not familiar with it. Some users add customizations
for this script to perform some specific startup task. Similarly, OBuild creates its own startup file named
obuild_startup.lxe
.
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.
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.
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 different OTHOME
.
A summary of current exit codes and their meaning:
Exit code | Meaning |
---|---|
0 | Build success |
400 | Bad command line option |
422 | Error while reading JAR Manifest |
404 | Error in the VM process classloader |
500 | Build contains errors |
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 user userx on Windows,
while when userx is building using Linux, it will be located at /home/userx
. Note that directories starting with .
on Linux are hidden.
opentext.ini
file, as with CSIDE.