Features

The purpose of the buildenv tool is to help projects to setup easily a build environment (based on Python virtual environment, or “venv”), just after clone, with minimal dependencies (i.e. only git and python).

Simple setup with loading scripts

The main feature of the buildenv tool is to generate loading scripts in the project root folder, ready to be executed just after the project is cloned, and loading everything so that the project is ready to build (whatever is the used build system).

See usage instructions for details.

New project

Any project can be simply setup to use buildenv by running a simple standalone python script in the project root folder:

  1. download buildenv script (python version) – wget https://raw.githubusercontent.com/dynod/buildenv/main/buildenv-loader.py

  2. launch it:

    • on Linux: python3 buildenv-loader.py

    • on Windows: python buildenv-loader.py

  3. you’re done, the project now also embeds buildenv loading scripts for a more convenient day to day use

Launch build terminal from explorer

By default, the loading scripts are spawning a new shell process. It means that when launched from the OS explorer (Windows/Linux), a build terminal will be launched, initialized with the build environment context, and stay openned to let you entering shell commands.

On Windows, it works with both:

  • buildenv.cmd: that will open the terminal in a cmd window (or better, in Windows Terminal if installed)

  • buildenv.sh: that will open the terminal in a git bash window (see gitforwindows.org)

Shared venv

You may work on multiple projects, and want to avoid to setup multiple build environments for each project.

The loading scripts automatically looks up in parent git folders to find an existing venv. If it finds one, it loads it instead of creating a new one in the current project folder.

Example layout:

projectA/
  + .git/
  + venv/
  + buildenv.*
  + projectB/
  |--+ .git/
  |--+ buildenv.*
  + subfolder/
  |--+ projectC/
     |--+ .git/
     |--+ buildenv.*

When loading scripts are used in projectB or projectC, the venv of projectA will be used.

Note

This behavior can be disabled by setting lookUp parameter to false in the configuration file.
In this case, the venv will always be created in project root folder.

Suggested git files

When the build env manager prepares the build environment, it will verify if some recommended git files exist in current project. If not, these files will be generated with default content:

  • .gitignore is configured so that virtual env and .buildenv folders are ignored and not pushed to source control

  • .gitattributes is configured to handle platform-specific files with correct line endings:

    • .bat and .cmd files must always use crlf line endings

    • .sh files must always use lf line endings

Completion

When running on Linux (or in Git bash on Windows), completion is automatically enabled when running in buildenv shell for following commands:

  • buildenv

  • pip

Completion can be enabled for other commands from buildenv extensions.

Extensions

The buildenv tool behavior can be extended, to perform:

  • extra steps during the build environment initialization

  • add activation scripts to be executed each time the build environment is loaded

Extensions are contributed by registering classes into the buildenv_init entry point in a given python module setup configuration. Referenced class must extend the buildenv.extension.BuildEnvExtension class.

Example syntax for entry point contribution:

[options.entry_points]
buildenv_init = 
	my_extension = my_package.my_module:MyExtensionClass

Limitations

The buildenv tool refuses to create a venv in a path containing space characters.
This decision has been made since in this case, some venv scripts (e.g. register-python-argcomplete) get their “shebang” line containing spaces, which is not supported.
It looks to be a limitation only on Linux, but using spaces in paths for development seems to be definitely a bad idea, so buildenv makes no difference and doesn’t support them on all platforms.