A source code mutation/transformation framework
A source code mutation/transformation framework.
HELIX defines three major primitives:
Core project layouts including templated boilerplate and methods for generating and building artifacts from a set of Components and Transforms.
Small, configurable pieces of source code that represent a specific implementation of a specific functionality along with associated metadata.
Modifications of either source code or a built artifact along with associated metadata.
Blueprints are configured with a collection of Components to include and Transforms to apply and then built to generate build artifacts.
Install HELIX from PyPI with pip, run:
pip install helix
Some Blueprints, Components, and Transforms include additional, non-python
dependencies that must be installed separately. These can be installed
automatically (if supported) with the
install command. For example, to
install dependencies for the
upx Transform, run:
helix install transforms upx
To install all dependencies for all installed Blueprints, Components, and Transforms, run:
Note: some Blueprints, Components, and Transforms include dependencies which
must be manually installed. Using the
install command for these will instead
list the dependencies that must be installed manually.
To list currently installed parts of HELIX:
To generate a single build, use the
build command. For example, to generate a
build using the
cmake-cpp blueprint, with the
component (setting the
second_word parameter to
foo), and apply the
transform (on supported platforms), writing output files to
helix build blueprint cmake-cpp ./example \ -c configuration-example:second_word=foo \ -t strip
build command also supports loading a configuration from a JSON file and
HELIX is fairly scriptable. See the
examples/ directory or take a look at the
full documentation for more.
HELIX is designed to be easily extensible via entry points. Blueprints, Components, and Transforms simply need to conform to their respective abstract base classes and be exposed under their respective entry point (see the Getting Started section of the documentation for more details and a tutorial). External Blueprints, Components, and Transforms that are correctly exposed are usable in all normal HELIX commands.
To set up a development environment, first clone this repo. Next, it is useful to install HELIX in editable mode with extras for development and testing:
pip install -e .[development,testing]
When developing new components it can be helpful to use HELIX's
in verbose mode so that you can see compiler and linker output and correct any
errors you may encounter:
helix build blueprint cmake-cpp novel-component -c novel-component -v
To build the full HELIX documentation, after installing HELIX with
development extras enabled, from the
docs/ directory, run:
Or other supported Sphinx output formats.
You can expose tests for your Components and Transforms by adding a subclass of
helix.tests.UnitTestCase to the entrypoint
helix.tests. Some useful testing
mixins are provided in
helix/tests.py and for some examples see the tests
To test the HELIX interfaces and utilities, run:
helix test system
To test Components, Blueprints, and Transforms, run:
helix test unit
DISTRIBUTION STATEMENT A. Approved for public release: distribution unlimited.
© 2021 Massachusetts Institute of Technology
- Subject to FAR 52.227-11 – Patent Rights – Ownership by the Contractor (May 2014)
- SPDX-License-Identifier: MIT
This material is based upon work supported by the Department of Defense under Air Force Contract No. FA8721-05-C-0002 and/or FA8702-15-D-0001. Any opinions, findings, conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the Department of Defense.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.