2017 June Release

Build and test environmentsPermanent link for this heading

In build and test environments it is necessary that Fabasoft app.ducx projects can be compiled and loaded using the command line instead of utilizing the Eclipse environment.

To ensure the quality of Fabasoft app.ducx projects an automatic test environment is recommended. Fabasoft app.ducx supports automatic compiling and loading of Fabasoft app.ducx projects in a Fabasoft Folio Domain utilizing Apache Ant. Thus appropriate tests can be carried out immediately after a successful build.

Additionally software products, software editions and software solutions can be extracted. The following chapter describes how to use Fabasoft app.ducx Ant tasks.

PrerequisitesPermanent link for this heading

Make sure that Apache Ant is properly installed. For more information about the installation and configuration of Apache Ant consult http://ant.apache.org/manual/index.html.

If problems with the Java heap size arise, the values for the Java heap size have to be adjusted accordingly (e.g. -Xms64m -Xmx1024m). This can be done by setting the ANT_OPTS variable.

  • set ANT_OPTS=-Xms64m -Xmx1024m (Microsoft Windows)
  • export ANT_OPTS="-Xms64m -Xmx1024m" or
    setenv ANT_OPTS "-Xms64m -Xmx1024m"  (Linux; depending on the shell)

Environment variablesPermanent link for this heading

The environment variable DUCX_HOME is used to specify the path to the needed libraries for compiling and loading. The libraries can be found here: http://update.appducx.com/Ant.zip. At least this environment variable must be set. For example, if you copy the Ant directory in the C:\appducxLibraries directory, set DUCX_HOME to C:\appducxLibraries.

The following environment variables may be used in the Fabasoft app.ducx project file. If this is the case, make sure that the environment variables are also set in the build environment or that the corresponding values are defined in the Apache Ant build.xml.

  • Environment variable for the web service configuration (e.g. DUCX_WEBSERVICECONFIGFILE)
    Defines the path to a Fabasoft Folio Web Service configuration file (.ducxws). This setting is necessary, if component object references should be updated or the project should be loaded in a Fabasoft Folio Domain.
    Note: To create a configuration file, edit the properties of a Fabasoft app.ducx project in Eclipse and uncheck Use default web service. Specify the properties of the web service as needed.
  • Environment variable for the copyright file (e.g. DUCX_COPYRIGHT)
    Defines the path to a copyright file of the software component defined by the Fabasoft app.ducx project.
  • Environment variable for the version (e.g. DUCX_VERSION)
    Defines the version of the software component defined by the Fabasoft app.ducx project.
    You are free to use any version number (an integer).
    Fabasoft uses a two digit schema (eg. 150000 to denote Version 15.0.0).
  • Environment variable for the target version (e.g. DUCX_TARGET)
    Defines the version of the Fabasoft Folio Domain the Fabasoft app.ducx project is compiled for. Available target versions: VERSION81, VERSION9, VERSION916, VERSION925, VERSION10, VERSION1016, VERSION1026, VERSION1036, VERSION1106, VERSION1116, VERSION1127, VERSION1132, VERSION12, VERSION1227, VERSION123, VERSION1225, VERSION1227, VERSION123, VERSION13, VERSION131, VERSION1313, VERSION132, VERSION1327, VERSION133, VERSION14, VERSION1408, VERSION141, VERSION1413, VERSION142, VERSION1427, VERSION143, VERSION15, VERSION150003,VERSION150301, VERSION16, VERSION17, VERSION171, VERSION172, VERSIONDEVELOPMENT, VERSIONEXPERIMENTAL, VERSIONSTAGING
  • Environment variable for the java compiler.
  • To ensure correct java libraries, the java compiler has to be specified by the environment variable DUCX_JAVA_HOME[_X] This variable is used to specify the java compiler required for specific versions of Fabasoft Folio. X stands for the java version. Currently most versions require Java 7 so to be sure that every java compiler from 7 up to the current version generates compatible code, set the variable in an appropriate way (e.g. DUCX_JAVA_HOME_7="C:/Java/jdk1.7.0_65).
  • The order of variable checking is
  • DUCX_JAVA_HOME_X
  • DUCX_JAVA_HOME
  • JAVA_HOME

If you compile a Fabasoft app.ducx project containing Java source code, the manifest of the generated JAR file can be populated with following environment variables:

  • DUCX_SPEC_TITLE=SPEC_TITLE (string)
    Defines the title of the specification.
  • DUCX_SPEC_VENDOR=SPEC_VENDOR (string)
    Defines the organization that maintains the specification.
  • DUCX_SPEC_VERSION=SPEC_VERSION (string)
    Defines the version of the specification.
  • DUCX_IMPL_TITLE (string)
    Defines the title of the implementation.
  • DUCX_IMPL_URL (string)
    Defines the URL from which the implementation can be downloaded from.
  • DUCX_IMPL_VERSION (string)
    Defines the version of the implementation.
  • DUCX_IMPL_VENDOR (string)
    Defines the organization that maintains the implementation.
  • DUCX_IMPL_SEALED (true|false)
    Should be set true because all classes defined in all package are archived in the same Fabasoft app.ducx JAR file.

Execute Fabasoft app.ducx Ant tasksPermanent link for this heading

To execute Fabasoft app.ducx Ant tasks you can copy and modify the ant-build-template.xml provided here: http://update.appducx.com/Ant.zip. Copy the file in a directory and rename the file to build.xml. Modify the build.xml file as described in chapter “Fabasoft app.ducx Ant tasks” and execute Apache Ant (ant).

AuthenticationPermanent link for this heading

There are two possible ways to authenticate the user against a Fabasoft Folio Web Service.

Basic authentication

With basic authentication, a username password pair is used to authenticate the user.

Basic Authentication Example

<target name="definewebsvc">
  <webservice id="websvc" url="your baseurl" timeout="your timeout">
    <authentication>
      <basic user="your username" password="your password"/>
    </authentication>
  </webservice>
</target>

Client Certificate

With client certificate authentication, a keystore and a truststore have to be supplied to authenticate against a Fabasoft Folio Web Service.

Client Certificate Example

<target name="definewebsvc">
  <webservice id="websvc" url="your baseurl" timeout="your timeout">
    <authentication>
       <clientcertificate>
         <keystore location="/ssl/keystore.p12" password="xxx" type="pkcs12" />
         <truststore location="/ssl/truststore.jks" password="xxx" type="jks" />
       </clientcertificate>
    </authentication>
  </webservice>
</target>

Fabasoft app.ducx Ant tasksPermanent link for this heading

Fabasoft app.ducx provides the following Ant tasks:

  • updaterefs
    The software component cache gets updated based on the defined web service in the Fabasoft app.ducx project file.
  • clean
    All intermediate files of a previous compilation are deleted.
  • cleanlangfiles
    Cleans up multilingual names and explanation texts not referenced in the source code anymore.
  • compile
    The defined Fabasoft app.ducx project is compiled.
  • load
    The defined Fabasoft app.ducx project is loaded in the Fabasoft Folio Domain based on the defined web service in the Fabasoft app.ducx project file.
  • extract
    The defined Fabasoft app.ducx project is extracted in a COO file.
  • extractsolution
    Software products, software editions and software solutions specified in the defined Fabasoft app.ducx project are extracted.
  • startcoverage
    Starts an app.ducx Expression coverage session. A coverage session will live as long until it is explicitly stopped. Sessions not stopped at service shutdown will be persisted and restarted at service startup.
  • stopcoverage
    Stops an app.ducx Expression coverage session and saves coverage data. For every software component, a coverage data file is provided.
  • ducxunittest
    Executes the unit tests defined in a given set of components.

To following XML fragment shows the main part of the build.xml file. For each project to be compiled define a ducx tag. Alternatively you can define one ducx tag with a base folder containing several projects to be compiled. Make sure that the copyright, version and target is specified within the build.xml file or within the .ducxproject file.

Core Example

<target name="definewebsvc">
  <webservice id="websvc" url="your baseurl" timeout="your timeout">
    <authentication>
      <basic user="your username" password="your password"/>
    </authentication>
  </webservice>
</target>

<target name="main" depends="declare, definewebsvc">
  <!-- define a ducx tag for each software component to compile -->
  <ducx ducxproject="d:/projects/Symb/.ducxproject" verbose="false">
    <!-- use the web service with ID "websvc" -->
    <webservice refid="websvc"/>
    <!-- define the tasks to be carried out -->
    <!-- clean up multilingual names and explanation texts -->

    <cleanlangfiles copyright="d:/projects/static/copyright.txt"/>
    <!-- delete intermediate files -->

    <clean/>
    <!-- update cache -->
    <updaterefs/>
    <!-- compile the app.ducx project -->
    <compile
      copyright="d:/projects/static/copyright.txt"
      version="1036"
      target="VERSION1036"
      coolib="${env.DUCX_HOME}/Ant/ducx/coolibj.jar"/>
    <!-- load the app.ducx project in a Fabasoft Folio Domain -->
    <load/>
    <!-- extract the app.ducx project to the specified file -->
    <extract target="runtime/symb.coo"/>
    <!-- extract the specified software solution to the target directory -->
    <extractsolution target="runtime" solution="SolutionSymb@200.200"/>
  </ducx>
  <!-- execute only some of the available tasks -->
  <ducx ducxproject="d:/projects/Jmb/.ducxproject" verbose="true">
    <clean/>
    <compile coolib="${env.DUCX_HOME}/Ant/ducx/coolibj.jar"/>
  </ducx>
  <!-- compile all projects in the defined root directory -->
  <ducx root="d:/projs" ducxproject=".ducxproject">
    <clean/>
    <compile coolib="${env.DUCX_HOME}/Ant/ducx/coolibj.jar"/>
  </ducx>
</target>

Single File Mode Example

<target name="main" depends="declare">
  <!-- define a ducx tag for each software component to compile -->
  <ducx ducxproject="d:/projects/Symb/.ducxproject" verbose="false" single="true">
    <!-- update cache -->
    <updaterefs/>
    <!-- delete intermediate files -->
    <clean/>
    <!-- compile the app.ducx project -->
    <compile
      copyright="d:/projects/static/copyright.txt"
      version="1022"
      target="VERSION1022"
      coolib="${env.DUCX_HOME}/Ant/ducx/coolibj.jar"/>
</target>

Coverage Example

<target name="coverage" depends="declare, coverage-start, coverage-play, coverage-stop"/>

<target name="coverage-start">
  <startcoverage session="compliance-session-id" verbose="false">
    <!-- session defines a variable name to write the session id into -->
    <!-- webservice defines connection -->
    <webservice url="your baseurl" timeout="your timeout">
      <authentication>
        <basic user="your user" password="your password"/>
      </authentication>
    </webservice>
    <!-- By defining an Edition all assigned components
        
(per Software Component Object or as textual reference)
         will be included in measuring -->
    <cover>your Edition</cover>
      <!-- There can be multiple Entries -->
    <cover>your component</cover>
  </startcoverage>
</target>

<target name="coverage-play">
  <!-- do whatever to produce events to be measured by coverage,
      
e.g. launch app.test, evaluate unit tests -->
</target>

<target name="coverage-stop">
  <!-- session is a variable holding a session id from a previous startcoverage task
       target is a directory, where coverage information will be placed in
       split defines the breakdown of the different coverage data into separate files

  
-->
  <stopcoverage session="${compliance-session-id}" target="coverage" verbose="false"
   split="true"/>
</target>

Unit Test Example

<target name="main" depends="declare, evaluate-unittests">
<target name="evaluate-unittests" depends="declare">
  <ducxunittest todir="./ducxunitresultdir">
    <!-- enables trace output matching flags and Java Regular Expression -->
    <trace enabled="true" flags="normal, warning, error" clienttimeout="100"
        servertimeout="1000">
      <include>.+unit test.+</include>
    </trace>
    <webservice refid="websvc"/>
    <!-- by defining an Edition all unit tests from the assigned components
        
will be executed -->
    <evaluate>your edition</evaluate>
    <!-- there can be multiple entries -->
    <evaluate>your component</evaluate>
    <evaluate>your unit test group</evaluate>
    <evaluate>your unit test</evaluate>
  </ducxunittest>
  <!-- generate a report e.g. JUnit report -->
</target>

Adding dynamic contents to the software componentPermanent link for this heading

When a software component is built in the single build mode, additional contents for the software components can be added dynamically without defining them directly in the software component.

To do so, the contents have to be copied in a predefined folder structure in the output folder build.

Following rules are applied in the build process:

  • Files ending with .refdoc in the help folder get CCT_DEVHELP as COOSYSTEM@1.1:compconttype and the prefix help:.
  • Files in a folder OperatingSystem get WSTYPE_OperatingSystem as COOSYSTEM@1.1:compcontwstype, if the type is available in the enumeration COOSYSTEM@1.1:WorkStationType. For example WINDOWS_X64 becomes WSTYPE_WINDOWS_X64 and get CCT_NORMAL as COOSYSTEM@1.1:compconttype.

Example

...

<target name="main" depends="declare, definewebsvc">
  <property name="project_dir" value="d:/projects/Symb/" />
  <copy file="${source_dir}/winx64.dll" todir="${project_dir}/build/WINDOWS_X64" />
  <copy file="${source_dir}/centos64.so" todir="${project_dir}/build/CENTOS_X64" />
  <copy file="${source_dir}/helpcontent.so" todir="${project_dir}/build/help" />
  <ducx ducxproject="d:/projects/Symb/.ducxproject" verbose="false" single="true">
    <!-- compile the app.ducx project -->
    <compile
      copyright="${project_dir}/copyright.txt"
      version="1227"
      target="VERSION12"
      coolib="${env.DUCX_HOME}/Ant/ducx/coolibj.jar"/>
  </ducx>
</target>

To add other files to the software component the .ducxproject file may contain a declaration within the <ns:SoftwareComponent> tag in the following format:

  • <ns:Content file="..." basename="..." type="" language="..." />
  • file
    Contains the absolute or relative file path, starting from the .ducxproject directory.
  • basename
    Contains the component content base name.
  • type
    One of the following values: CCT_DEVHELP, CCT_HELP, CCT_NORMAL.
  • language
    One of the following values: LANG_GERMAN, LANG_ENGLISH, ...

Example

...

<ns:SoftwareComponent>

    ...

    <ns:Content
       file="resources/LANG_GERMAN/help-HELPSampleUsrGer.chm"
       basename="help:HELPSampleUsrGer.chm"
       type="CCT_HELP"
       language="LANG_GERMAN"/>

...

</ns:SoftwareComponent>

Update app.ducx librariesPermanent link for this heading

To update the app.ducx libraries, download the app.ducx image from http://update.appducx.com/appducx.iso and mount it or burn the image on a writeable media. Replace the current libraries from the directory and subdirectories as defined in the environment variable DUCX_HOME and update the build.xml if necessary. Fore more information about the environment variables see chapter “Environment variables”.