Making a custom post-build action extension¶
This is an extension example for the following use case:
After performing a build for any of my releng-tool projects, I want to automatically add a series of files into the output directory before we attempt to package the contents. I want to do this using an extension to avoid the need to repeat the process across all my releng-tool projects.
Prelude¶
This extension example uses the name
my-awesome-extension
. Developers are free to change this with whatever name is applicable for their own extension.This extension example assumes a Python 3-supported interpreter. Developers looking to support running under a Python 2 interpreter may require additional steps not covered in this tutorial.
This tutorial does not cover steps on publishing an extension to an index such as PyPI. Instead, steps will be provided to load a extension’s sources into the system path for releng-tool (which is optional whenever a given extension can be installed from an index or runs in an environment that already manages the installation of the extension).
Creating the post-build action extension¶
A first step is to setup the initial file structure for the extension. Assuming
there exists a checked out releng-tool project (my-releng-tool-project
) to
be tested against, create a new extension folder named my-awesome-extension
alongside the releng-tool project(s):
├── my-awesome-extension/
│ ├── my_awesome_extension/
│ │ ├── assets/
│ │ │ └── NOTICE.pdf
│ │ └── __init__.py
│ ├── LICENSE
│ ├── README.md
│ ...
└── my-releng-tool-project/
Inside this folder, create any base documents desired, a sample PDF, as well
as preparing a my_awesome_extension
Python package folder to hold the
extension implementation. For the __init__.py
file, add the following
contents:
import os
import shutil
def releng_setup(app):
app.connect('post-build-finished', my_awesome_postbuild_handler)
def my_awesome_postbuild_handler(env):
print('post-build triggered!')
The above adds a function releng_setup
, which releng-tool uses to register
the extension into the releng-tool engine. The function is invoked during
initialization by passing an application context (app
) which the extension
can use to hook onto events and more. This extension implements a function
my_awesome_postbuild_handler
, which is registered on the post-build-finished
event. This allows the handler to be triggered when a post-build stage has
completed for a project.
To test that the post-build event is triggered, use an existing releng-tool project and register this new example extension into the releng-tool process:
import os
import sys
...
extensions = [
'my_awesome_extension',
]
# add local extension path into system path
container_dir = os.path.dirname(ROOT_DIR)
ext_dir = os.path.join(container_dir, 'my-awesome-extension')
sys.path.append(ext_dir)
When running releng-tool, the following message should be printed at the end of a run:
$ releng-tool
...
post-build triggered!
(success) completed (0:00:00)
Next, we can now adjust our handler to help modify the output directory
when the event is triggered. In this example, we want to copy an
extension-managed NOTICE.pdf
file and place it into the output directory.
Update the extension with the following:
def my_awesome_postbuild_handler(env):
# find the NOTICE PDF document
ext_dir = os.path.dirname(os.path.realpath(__file__))
assets_dir = os.path.join(ext_dir, 'assets')
notice_pdf = os.path.join(assets_dir, 'NOTICE.pdf')
# copy this file into the target directory
target = os.path.join(env['TARGET_DIR'], 'NOTICE.pdf')
shutil.copyfile(notice_pdf, target)
With this change, a re-run of the releng-tool project should have the
NOTICE.pdf
document copied into the target directory for the project.
This concludes this tutorial.
For a list of available API interfaces and documentation for these interfaces, see the documentation found inside the API implementation.