Skip to content

Latest commit

 

History

History
 
 

build

README.md

OSCAL Build Tools

This subdirectory contains infrastructure used to create OSCAL-related artifacts (e.g., schemas, converters) and perform status checks. Below are instructions for using these tools.

Prerequisites

The build tools in this directory require a Unix environment with the following software:

  • Maven: Required to generate artifacts
  • NodeJS (ensure the version matches .nvmrc): Required to perform link checking
  • libxml: Provides xmllint which is required to validate generated XML artifacts

Additionally ensure your environment has standard build tools such as git 2.34.1 or newer, make 4.3 or newer, zip 3.0 or newer, and bash 3.2 or newer for syntax we require.

Overview

All OSCAL build targets are defined in a Makefile. To summarize the build targets, run make help. To generate all artifacts and run all checks, simply run make all.

To run targets in parallel, pass a --jobs <n> flag, where <n> is the number of concurrent jobs and should be <= your machine's core count. Note that running jobs concurrently will make the output harder to follow and debug.

Artifact Generation

As of v1.1.0, artifacts are no longer tracked in the OSCAL git repository (discussion link). Instead artifacts are generated as part of a release.

Developers can generate schemas locally using the make artifacts command.

Developers can also generate individual artifacts using the following commands:

  • make schemas: Generates the JSON Schemas and XSDs off of the source Metaschemas;
  • make converters: Generates the XSLT stylesheets for JSON<->XML conversion off of the source Metaschemas.

Checks

Developers can run checks using the make checks command.

The checks can also be run individually:

  • make linkcheck: Checks each markdown file in the repository for bad links;
  • make validate-jsonschemas: Validates that the JSON schemas generated by make schemas are schema valid against the JSON Schema specification;
  • make validate-xsds: Validates that the XSD files generated by make schemas are schema valid against the XSD specification;
  • make test-profile-resolution: Runs the test suite in /src/utils/resolver-pipeline.

Archive Generation

make archives generates .zip and .tar.bz2 archives with the generated artifacts.

By default, archives will have the suffix SNAPSHOT, but this can be overridden using the RELEASE variable:

$ make archive RELEASE=my_release