Skip to main content

Build DPKGs natively with Python.

Project description

deb-constrictor

Build Debian Packages (.deb/DPKGs) natively in Python. No dependencies on Java, Ruby or other Debian packages.

Install

Using pip:

pip install deb-constrictor

Usage

Define directories, links, scripts and dependencies:

from constrictor import DPKGBuilder, BinaryControl

dirs = [
    {
        'source': '~/python/beneboyit/frontend/src',
        'destination': '/srv/python/bbit-web-frontend',
        'uname': 'www-data'
    }
]

maintainer_scripts = {
    'postinst': '~/python/beneboyit/frontend/scripts/after-install',
    'preinst': '~/python/beneboyit/frontend/scripts/before-install'
}

links =  [
    {
        'path': '/etc/nginx/sites-enabled/bbit-web-frontend',
        'target': '../sites-available/bbit-web-frontend'
    },
    {
        'path': '/etc/uwsgi/apps-enabled/bbit-web-frontend.ini',
        'target': '../apps-available/bbit-web-frontend.ini'
    },
]

depends = ('nginx', 'uwsgi')

output_directory = '~/build'

c = BinaryControl('bbit-web-frontend',  '1.5', 'all', 'Ben Shaw', 'BBIT Web Frontend')

c.set_control_field('Depends', depends)

c.set_control_fields({'Section': 'misc', 'Priority': 'optional'})

d = DPKGBuilder(output_directory, c, dirs, links, maintainer_scripts)
d.build_package()

Output file is named in the format .deb and placed in the destination_dir. Alternatively, provide a name for your package as the output_name argument, and the package will be created with this name in the output_directory.

constrictor-build tool

constrictor-build is a command line tool that will build a package based on information in a JSON file. By default, this file is in the current directory and called "build-config.json".

It loads the following fields and expects them to be in the same format as above:

  • package (string, required)
  • version (string, required)
  • architecture (string, required)
  • maintainer (string, required)
  • description (string, required)
  • extra_control_fields (dictionary of standard DPKG control field pairs, optional)
  • directories (array of dictionaries as per example above, optional)
  • links (array of dictionaries as per example above, optional)
  • configuration_files (array of strings, can be paths or globs to match multiple)
  • maintainer_scripts (dictionary as per example above, optional)
  • parent (string, optional, see parent section below)
  • deb_constrictor (dictionary, optional, see deb_constrictor section below). Valid keys are:
    • ignore_paths (array of string, optional)
    • environment_variables (array of two-element arrays, optional)
    • variables (array of two-element arrays, optional)
    • commands (dictionary)

Examples of configuration files and how you might use constrictor-build in conjunction with other build steps are included in the examples directory.

Environment variables in the form ${var_name} or $var_name will be substituted.

parent

You can also provide a "parent" field, which is a path to another build JSON file (path is relative to the config file) from which to read config values. For example, you might want to define the sections only in a parent config rather than in each child config. The parent lookup is recursive, so a parent can have a parent, and so on. constrictor-build also attempts to load a base configuration file as the root of the configuration tree. The default location of this file is ~/constrictor-build-config.json, but can be overridden by setting the CONSTRICTOR_BUILD_BASE_CONFIG_PATH environment variable.

Child values will replace parent values. Fields that are lists or dictionaries will be appended to/updated as appropriate. Items in child configuration lists will not be added to the parent configuration if they already exists; this means that if a parent and child both define the same Depends, or directory to include (for example), they won't be included twice in the computer configuration,

For example, a parent with this configuration:

{
  "extra_control_fields": {
      "Depends": ["some-package"]
  }
}

Could be overridden with a child with this configuration:

{
  "extra_control_fields": {
      "Depends": ["some-other-package"],
      "Provides": ["this-package"]
  }
}

Creating a computed configuration like this:

{
  "extra_control_fields": {
      "Depends": ["some-package", "some-other-package"],
      "Provides": ["this-package"]
  }
}

deb_constrictor

Provides a dictionary of metadata to configure build options such as file exclusion, pre/post build actions or variables. Valid keys are:

  • ignore_paths (array of strings, optional)
  • environment_variables (array of two-element arrays, optional)
  • variables (array of two-element arrays, optional)
  • commands (dictionary of arrays, optional)

ignore_paths

List of glob patterns of files to exclude when assembling data tar. Files are compared with their name relative to the included directory, and have a leading slash.

For example, on the file system, you have directory layout like so:

  • src
  • src/media/
  • src/media/123.jpg
  • src/media/456.jpg

And your build-config.json specifies a directory with source src/. To exclude all the jpg files in the media directory, set you ignore_paths to this:

"ignore_paths": ["/media/*.jpg"]

In this case though, the media directory will be empty (as it only contained .jpg files) and so would not be included in the archive at all. This might not be desirable if you want an empty directory to be deployed.

The solution to this is to add a placeholder file in the directory that would otherwise be ignored - it should be called either .gitkeep or .depkeep. If this file is found its containing directory will be added to the archive (as it is not empty) however the placeholder file will not be included.

environment_variables, variables

An array of two-element arrays in the format [key, value]; this format is used instead of a dictionary to preserve order so that values may depend on values that have been defined earlier.

environment_variables and variables both behave in the same way in that any values they define can be used to interpolate variables throughout the configuration, however if calling external scripts (e.g. pre/post build scripts) then only environment_variables will be passed to the sub-process.

Here's an example using variables.

{
  "package": "${VENV_NAME}",
  "deb_constrictor": {
    "variables": [
      ["BUILD_DIR", "build"]
    ],
      "environment_variables": [
        ["PYTHON_VERSION", "3.6"],
        ["VENV_NAME", "example-virtualenv"],
        ["VENV_DIR", "${BUILD_DIR}/${VENV_NAME}"],
        ["VENV_BIN_DIR", "${VENV_DIR}/bin"]
      ]
  },
  "directories": [
    {
      "source": "${BUILD_DIR}/virtualenvs/${VENV_NAME}",
      "destination": "/var/virtualenvs/${VENV_NAME}"
    }
  ]
}

After the variables are interpolated the configuration will be like this:

{
  "package": "example-virtualenv",
  "directories": [
    {
      "source": "build/virtualenvs/example-virtualenv",
      "destination": "/var/virtualenvs/example-virtualenv"
    }
  ]
}

Variable resolution order is variables, then environment_variables, then os.environ, i.e. a key will first be looked up in variables, if it does not exist then environment_variables, and so on to os.environ.

The variables values will only be used to interpolate the configuration while the environment_variables values will be exported to any sub processes being called, so in this example, PYTHON_VERSION, VENV_NAME, VENV_DIR and VENV_BIN_DIR will be added to os.environ, while BUILD_DIR will not.

commands

Commands can be supplied to be run before and after building. For example, to setup a virtualenv for packaging, and to upload the built .deb to an apt repository afterwards.

The supported keys for the commands are prebuild and postbuild, which will be called before and after (respectively) the DPKG being created. The commands should be supplied as an array (as would be sent to subprocess.call).

When using parent config files, commands defined in children override those in parents (as opposed to appending).

Two special variables are set (in addition to other defined variables) which are interpolated into the commands and set in the environment:

  • DEB_CONSTRICTOR_WORKING_DIR: the directory containing the current config file being used (e.g. for /foo/bar/build-config.json, this value is /foo/bar)
  • DEB_CONSTRICTOR_OUTPUT_PATH: the output path of DPKG, relative to the cwd. This variable is only set for postbuild. This can be combined with the working dir path to get absolute path.

An example of using these:

{
  "deb_constrictor": {
    "commands": {
      "prebuild": ["build-virtualenv.sh"],
      "postbuild": ["scp", "${DEB_CONSTRICTOR_OUTPUT_PATH}", "apt@apt-server.example.com/srv/apt/incoming/"]
    }
  }
}

The prebuild command build-virtualenv.sh has access to the DEB_CONSTRICTOR_WORKING_DIR environment variable (as well as other environment_variables that have been defined) and can refer to all of these to execute tasks.

This example shows that postbuild command that will be interpolated before being executed, so the actual command that is called might be:

scp build/example-1.0_amd64.deb apt@apt-server.example.com/srv/apt/incoming/

remove_after_build

If True, then the DPKG will be deleted after building, or more specifically, after the postbuild command has been run (it will be deleted even if a postbuild command does not exist though).

This is intended to be used to clean up a DPKG that is no longer needed, for example, if the postbuild script sends it to a remote server.

Known Issues

  • Can only make Binary packages
  • As with any tar based archive, ownership of files based on uname/gname can be wrong if the user does not exist. Use with caution or create postinst scripts to fix.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

deb-constrictor-0.9.tar.gz (19.1 kB view details)

Uploaded Source

Built Distributions

deb_constrictor-0.9-py3.9.egg (32.1 kB view details)

Uploaded Egg

deb_constrictor-0.9-py3-none-any.whl (17.8 kB view details)

Uploaded Python 3

File details

Details for the file deb-constrictor-0.9.tar.gz.

File metadata

  • Download URL: deb-constrictor-0.9.tar.gz
  • Upload date:
  • Size: 19.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/4.3.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.0 CPython/3.9.4

File hashes

Hashes for deb-constrictor-0.9.tar.gz
Algorithm Hash digest
SHA256 601fa7b9434dffac10a43d764f3bba1c40276c6458b699bf67a26b0758bc7b2b
MD5 f8f3d9f423bc92109eed485fcd25e09e
BLAKE2b-256 44e19274602f5324d8d61a0c02462e5c6c98292bfde7244182dae0d983004878

See more details on using hashes here.

File details

Details for the file deb_constrictor-0.9-py3.9.egg.

File metadata

  • Download URL: deb_constrictor-0.9-py3.9.egg
  • Upload date:
  • Size: 32.1 kB
  • Tags: Egg
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/4.3.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.0 CPython/3.9.4

File hashes

Hashes for deb_constrictor-0.9-py3.9.egg
Algorithm Hash digest
SHA256 e65247043862b3c3cc361fce142e21db8503db823ea4cf6bc9f2a26e0732e4a7
MD5 82cbc02ce5e605d742a1b89959934b9c
BLAKE2b-256 3ff2194c8a4597c4b16b9b3fd03defe748bf951be7cf27ed5f065999d57dc930

See more details on using hashes here.

File details

Details for the file deb_constrictor-0.9-py3-none-any.whl.

File metadata

  • Download URL: deb_constrictor-0.9-py3-none-any.whl
  • Upload date:
  • Size: 17.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/4.3.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.0 CPython/3.9.4

File hashes

Hashes for deb_constrictor-0.9-py3-none-any.whl
Algorithm Hash digest
SHA256 1b5f792368da227f5e651f8a9783c966e12f5f080303451d92051f324ed91f15
MD5 3b670c7c364ae4cbd1cea3a363294475
BLAKE2b-256 87809b372deaf354e5c6ad405c10ebd6b914b18d9e4430069574979e4f5bd9c5

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page