Configuring Structure101 Build

Structure101 Build can be added to your existing CI processes to check for new structural violations and deteriorating key measures.

Structure101 Build is delivered as a zip archive. Installation is simply unpacking to a suitable folder location. The core jar file is structure101-java-build.jar.   A minimum Java 8 is the only requirement for running the Build process.

The build process is configured using an XML file. This is typically located in the project root folder alongside the Studio (.hsp) and Workspace (.hsw) files.
Any and all paths in these files should use const(THIS_FILE) to ensure the paths resolve correctly regardless of the root folder location.

The Build process is run with a simple command line passing the configuration file as the only argument: –

java -jar <path-to>/structure101-java-build.jar structure101-build-configuration.xml

Below is a simple example configuration file that runs the check-spec operation.

<?xml version="1.0" encoding="UTF-8"?>
<headless version="1.0">
    <operations>
        // check for structure spec violations
        <operation type="check-spec">
           <argument name="output-dir" value="const(THIS_FILE)/s101-results"/>
            <argument name="onlyNew" value=“true"/>
            <argument name="check-unassociated" value="true"/>
            <argument name="fail-on-violations" value="false"/>
            <argument name="identifier-on-violation" value="build unstable"/>
        </operation>
   </operations>
   <arguments>
       <argument name="local-project" value="const(THIS_FILE)/structure101-studio.java.hsp">
        </argument>
    </arguments>
</headless>

The operations block contains the operations to be run. They are executed in the order they appear in the file. The arguments block must contain the local-project argument. The classpath that Build will analyse can be taken from the local project file or through an override to the local-project argument.

The simplest setup (shown above) is to reference the local Studio project file from which build will take the classpath. The repository URL and project name are also taken from the local project file. [For version 5.0.14385 and earlier the project and repository arguments must be supplied]

All three can be overridden in the configuration XML. The repository URL and project name are overridden using the repository and project arguments.

<arguments>
       <argument name="local-project" value="const(THIS_FILE)/structure101-studio.java.hsp">
        </argument>
        //Override the .hsp file
        <argument name="repository" value="c:\structure101-repository"/>
        <argument name="project" value="S101 Example"/>
    </arguments>
</headless>

The classpath is overridden using the override classpath attribute. In this example classpathentry elements are being used so that module names can be defined. This form should be used if you are using a Workspace derived Studio project.

<arguments>
    <argument name="local-project" >
        <override attribute="classpath">
            <classpathentry kind="lib" path="const(THIS_FILE)/util/build/classes/java/main" module="util"/>
            <classpathentry kind="lib" path="const(THIS_FILE)/nalpeiron/build/classes/java/main" module="nalpeiron"/>
        </override>
   </argument>
   <argument name="repository" value="c:\structure101-repository"/>
   <argument name="project" value="Extract Module Example"/>
</arguments>

In the final example below the classpath override attribute value is used to define a traditional delimiter separated classpath.
Also in this example the local-project value is omitted. In this case the classpath override, repository and project arguments are mandatory.

<arguments>
    <argument name="local-project">
        <override attribute="classpath" value="C:\classes-to-parse;c:\more-classes-to-parse"/>
    </argument>
    <argument name="repository" value="C:\repository"/>
    <argument name="project" value="my-project"/>
</arguments>