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

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.

OBuild package

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

Adding OBuild to Windows PATH

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.

Command shell with OBuild help printed

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.

C:\Users\userx>obuild -h usage: OBuild --OTHOME --SRCDIR [--DSTDIR ] [--VERBOSE] OBuild --VERSION OBuild -h OpenText OBuild version 22.4.0.v20220913_02529 -- a tool to build OScript code against a content server OTHOME -h,--HELP Show this message. -v,--VERSION Print version information and exit. -ot,--OTHOME The directory where Content Server is installed. -src,--SRCDIR The directory that contains the source OScript modules directories. -dst,--DSTDIR < directory> The directory that built items get written to. If not specified, current directory is used. -verbose,--VERBOSE Print verbose logging. C:\Users\userx>obuild --VERSION OpenText OBuild version 22.4.0.v20220913_02529

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.

obuild --OTHOME C:\OPENTEXT\qa224 --SRCDIR C:\workspace\obuild\srcmodules2 --DSTDIR "C:\workspace\obuild\out" --VERBOSE

--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.

C:\Users\userx>obuild -ot C:\notexists Not valid othome: 'C:\notexists' ERROR - parameter OTHOME is either missing or invalid. Process Exit code 400: Bad command line option

obuild_startup.lxe

CSIDE creates a special startup script in the OTHOME usually named 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.

--SRCDIR

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

Output directory listing

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.

Module directory listing

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 .

OBUILD INFO building module C:\workspace\obuild\srcmodules2\channel OBUILD INFO build ospace: C:\workspace\obuild\srcmodules2\channel\CHANNEL_TEST 19:38:31,063 WARN Assigned id: 257 for ospace C:\workspace\obuild\out\staging\channel\ospace\channel_test.oll OBUILD ERROR parseError Object CHANNEL_TEST::RESTAPIUnitTest::NodesFromRecords inherits from non-existent object RESTAPI::UNITTESTSTUBS::GETNODESFROMRECORDS : C:\workspace\obuild\srcmodules2\channel\CHANNEL_TEST/RESTAPIUnitTest/NodesFromRecords.os : 3 : 41 : 3 19:38:31,066 ERROR Bad parent object ID in CreateOrphaned( #0, #0 ) OBUILD ERROR parseError Object CHANNEL_TEST::RESTAPIUnitTest::NodesFromRecords inherits from non-existent object RESTAPI::UNITTESTSTUBS::GETNODESFROMRECORDS : C:\workspace\obuild\srcmodules2\channel\CHANNEL_TEST/RESTAPIUnitTest/NodesFromRecords.os : 3 : 41 : 3 19:38:31,067 ERROR Bad parent object ID in CreateOrphaned( #0, #0 ) OBUILD ERROR parseError Object CHANNEL_TEST::RESTAPIUnitTest::nodes_v2_Update inherits from non-existent object RESTAPI::UNITTESTSTUBS::NODES_V2::PUT::NODEUPDATE::UPDATE::SUCCESS::UPDATE : C:\workspace\obuild\srcmodules2\channel\CHANNEL_TEST/RESTAPIUnitTest/nodes_v2_Update.os : 3 : 40 : 3 19:38:31,067 ERROR Bad parent object ID in CreateOrphaned( #0, #0 ) OBUILD ERROR parseError Object CHANNEL_TEST::RESTAPIUnitTest::nodes_v2_Update inherits from non-existent object RESTAPI::UNITTESTSTUBS::NODES_V2::PUT::NODEUPDATE::UPDATE::SUCCESS::UPDATE : C:\workspace\obuild\srcmodules2\channel\CHANNEL_TEST/RESTAPIUnitTest/nodes_v2_Update.os : 3 : 40 : 3 19:38:31,067 ERROR Bad parent object ID in CreateOrphaned( #0, #0 ) OBUILD ERROR Exception occurred during build com.opentext.oscript.OScriptVMException: Build of 'C:\\workspace\\obuild\\out\\staging\\channel\\ospace\\channel_test.oll' failed OBUILD INFO Build failed with 5 errors, 18 warnings Process Exit code 500: Build contains errors Check full logs at 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.

OBUILD DEBUG Converting WebLingo file C:\workspace\obuild\srcmodules2\channel\help\fn-read-news-p.htm using character set UTF-8 OBUILD INFO weblingocompiler compiled filename= C:\workspace\obuild\srcmodules2\channel\help\fn-read-news-p.htm annotation=null OBUILD DEBUG Converting WebLingo file C:\workspace\obuild\srcmodules2\channel\help\fn-summary-p.htm using character set UTF-8 OBUILD INFO weblingocompiler compiled filename= C:\workspace\obuild\srcmodules2\channel\help\fn-summary-p.htm annotation=null OBUILD INFO Build successfully with 0 errors, 74 warnings

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

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

This optional option is advised if you want to see more detailed logs, for example, if you have an issue with OBuild and are sending the logs to OpenText. It affects, on the current implementation, the logs inside OBuild itself, not inside the Oscript thread logs. To change the verbosity of the OScript thread logs, edit the opentext.ini file, as with CSIDE.

Feedback

OBuild is the result of previous feedback. Our customers asked for a tool to automate the build of OScript modules they own. Please create a ticket with Customer Support for CSIDE, and it will be forwarded to us. Also, you can post your questions, suggestions, and feedback on the forum. Your feedback helps us to continously improve our software to meet your expectations.