build

Developer Guide for oscal-content

This directory contains infrastructure used to generate OSCAL document instances and perform checks upon them.

Prerequisites

The build tools in this directory require a Unix environment that meets those outlined in the OSCAL submodule's build instructions in its build/README.md file for the relevant tag or commit. For a quick reference, here is the current version of this guidance on the latest version of the develop branch.

Building

Overview

All oscal-content 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.

If you want to run make commands outside of this directory, for example from the top-level directory of this repository cloned onto a developer workstation, use the -C argument, such as make -C ./build all.

By default, the destination for all generated content is in the generated sub-directory. To generate content "inline" like the GitHub Actions CI/CD automation, you want to change the GEN_CONTENT_DIR relative to location of the Makefile. Either executing make -C build all GEN_CONTENT_DIR=.. from the top-level directory or executing make all GEN_CONTENT_DIR=.. from this directory are correct. Either will generate source content in src/nist.gov and examples into nist.gov and examples, respectively.

Build OSCAL Tools and Install Dependencies

You can use the make all to build the necessary schemas and content converters in addition to other steps, or use specific targets to build and install accordingly.

make build
make dependencies

Artifact Generation

You can use the make artifacts to generate all artifacts in addition to other steps, or you can use specific target(s) to generate a specific artifact.

make copy-readmes
make copy-xml-content
make resolve-xml-profiles
make convert-min-json-content
make reformat-json-content
make convert-yaml-content

Checks

You can use the make checks to validate generated artifacts in addition to other steps, or you can use specific target(s) to generate a specific artifact.

make validate-xml-content
make validate-json-content
make validate-yaml-content

Cleaning Dependencies and Artifacts

You can use the make clean to clean all artifacts generated from make all or other artifact generation targets. You can als also use any of the targets below to clean specific generated artifacts, while choosing to preserve others.

make clean-build
make clean-dependencies
make clean-readmes
make clean-json-content
make clean-xml-content
make clean-yaml-content