| Name | brock JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Brock |
| upload_time | 2024-10-26 07:55:30 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | Copyright (c) 2021 The Python Packaging Authority Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
build
docker
toolchain
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Bender Robotics command management system
Brock is a Python-based automation tool for launching commands in various
executors like Docker or remote systems. It was designed mainly for building
and testing automation of embedded software in Docker-based executors.
## Installation
### Prerequisities
Brock needs Docker to be installed and configured properly:
1. Install [Windows Subsystem for Linux 2](https://docs.microsoft.com/cs-cz/windows/wsl/install-win10).
2. Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop).
3. Switch to Windows containers if the executor is Windows-based - click Docker
Desktop icon and select Switch to Windows containers... (requires Windows Pro
or Enterprise), or turn experimental features on - open Docker Desktop, go to
Settings -> Docker Engine, set `"experimental": true` (allows to use Linux
and Windows containers simultaneously).
### Brock
You can install Brock from BR's pypi, download wheel from release page or
build it yourself - see [Contributing](#Contributing)...
```shell
$ pip install brock
```
## Usage
Brock scans all directories from drive root to current directory and looks
for `.brock.yml` config files. The format of the files is described in
[example_brock.yml](example_brock.yml).
The configuration files are merged together, the highest priority config file
is the one in the current directory. Individual config files don't have to be
complete, however, the merged configuration must contain all required
parameters.
The lowest priority config file determines the base directory which will be
used as a working directory for the executor (e.g. mounted to docker, mounted
over SSH). The commands should not access files outside this directory.
The list of all available commands is provided by `brock --help`, let's assume
a command `test` was defined in the `.brock.yml`, you can run it like this:
```shell
$ brock test
>> Executor not running -> starting
>> Pulling image python:3.9
./debug/test -s
Unity test run 1 of 1
-----------------------
483 Tests 0 Failures 0 Ignored
OK
```
If the required executor is not running, it is started automatically when
executing a command. It stays running until it is explicitly stopped by
`brock --stop`. The executors can also be restarted (e.g. to fetch changes in
the brock configuration) by `brock --restart`. The current state of the
executors is printed by `brock --status`.
The docker image can be pulled again or rebuilt (if using Dockerfile) using
`brock --update`.
If needed, you can launch a custom command directly in the executor by
`brock exec`:
```shell
$ brock exec @python 'python --version'
Python 3.9.10
```
Optionally, quotes or double-dash (`--`) can be used to avoid brock collecting
options destined to the command launched by executor:
```shell
$ brock exec @python "python --version"
Python 3.9.10
$ brock exec @python -- python --version
Python 3.9.10
If using a custom Docker registry, do not forget to login into the registry
before using `brock` - use full registry path including image name and tag:
```shell
$ docker login $IMAGE_REGISTRY
Username: $USER_NAME
Password:
Login Succeeded
```
If using Docker executor, you can launch a shell using `brock shell` (default
executor will be used if ommited):
```shell
$ brock shell @gcc
root@6bf119cb7b6a:/host# exit
exit
```
Brock sets the following predefined environmental variables:
- `BROCK_HOST_PATH` - absolute path to current directory on host
- `BROCK_HOST_PROJECT_PATH` - absolute path to project root on host
- `BROCK_RELATIVE_PATH` - relative path from project root to current directory
Additional variables can be set using the config option `env` for each executor.
#### Options
Brock offers the possibility of options in commands.
Configuration of options in .brock.yaml (see example_brock.yml)
opt-name:
- flag: str | None -> option is a flag e.g. `brock build --verbose`
- argument: str | None -> option is an argument e.g. `brock build something`,
can be * then an unlimited number of arguments is accepted
- default: any | None -> any value
- choice: list[str] -> list of acceptable values, brock checks input is in choice and also displays it in help
- variable: str | None -> optional custom name of the variable inside the session, to avoid any conflicts with built-in variables
- help: str | None
### Isolation types
The Brock can detect Windows version and the version of the Windows Docker
image, the needed isolation mode is determined automatically - if possible,
the image is started in `process` isolation, `hyperv` is used otherwise.
### Volume synchronization
To achieve satisfactory performance when using Linux containers on Windows
(or macOS), the project folder needs to be mounted more efficiently. For this
purpose, two volume synchronization mechanisms are available: Rsync or Mutagen.
#### Rsync
An additional container with Rsync is started - the project folder is mounted to
this container together with a named volume (that will reside inside the Linux
host) and these folders are then being synced using Rsync. To turn this feature
on, use the `sync` option in the config file.
Optionally, specific files/folders can be excluded from sync using
configuration option `exclude` under `sync` section.
#### Mutagen
Another option to synchronize volumes on macOS or Windows is to use
[Mutagen Extension](https://mutagen.io/documentation/docker-desktop-extension)
for Docker Desktop. Before use, it must be installed first:
```shell
docker extension install mutagenio/docker-desktop-extension:latest
```
Then, a cache must be created for each path which should be synchronized. Go to
Docker Desktop -> Extensions -> Mutagen, click Create Cache and enter the
project root path. Finally, configure the executor to use Mutagen
volume synchronization (see `example_brock.yml`).
### Devices in Docker executor
The docker can use the system devices if passed correctly, however this only
works when running a native container - e.g. a Windows container with the same
system version as the Windows host, or a Linux container under a Linux host.
Check the `devices` section of the config file.
## Build
Please first apply all steps in [contributing section](#Contributing).
After that you can call build scripts:
```shell
$ python build/build.py # builds the package
```
You can find build artifacts in the newly created dist folder.
## Contributing
Here is a short guide to ease you up contributing.
Start by installing virtual environment package
```shell
$ pip install virtualenv
```
Then create your own virtual environment
```shell
$ virtualenv venv
```
Now you should see venv folder in the project structure.
Activate virtual environment
```shell
$ source venv/bin/activate # on linux
$ venv\Scripts\activate.bat # on windows
```
After that you should see (venv) as prefix to your command line cursor.
Note you need to repeat activation every time you close the terminal.
To install the package in development mode call:
```shell
$ pip install -e .
```
Now you can call Brock directly from the command line and all changes to the
source code are instantly applied.
Raw data
{
"_id": null,
"home_page": null,
"name": "brock",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "build, docker, toolchain",
"author": null,
"author_email": "\"Bender Robotics s.r.o\" <opensource@benderrobotics.com>",
"download_url": "https://files.pythonhosted.org/packages/5b/29/3f2d3d4ef4bf9bf706a92af68c180a5254b9cd8d28e8c7faf9d896dad6f4/brock-0.1.0.tar.gz",
"platform": null,
"description": "# Bender Robotics command management system\nBrock is a Python-based automation tool for launching commands in various\nexecutors like Docker or remote systems. It was designed mainly for building\nand testing automation of embedded software in Docker-based executors.\n\n\n## Installation\n\n### Prerequisities\nBrock needs Docker to be installed and configured properly:\n1. Install [Windows Subsystem for Linux 2](https://docs.microsoft.com/cs-cz/windows/wsl/install-win10).\n2. Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop).\n3. Switch to Windows containers if the executor is Windows-based - click Docker\n Desktop icon and select Switch to Windows containers... (requires Windows Pro\n or Enterprise), or turn experimental features on - open Docker Desktop, go to\n Settings -> Docker Engine, set `\"experimental\": true` (allows to use Linux\n and Windows containers simultaneously).\n\n### Brock\nYou can install Brock from BR's pypi, download wheel from release page or\nbuild it yourself - see [Contributing](#Contributing)...\n```shell\n$ pip install brock\n```\n\n## Usage\nBrock scans all directories from drive root to current directory and looks\nfor `.brock.yml` config files. The format of the files is described in\n[example_brock.yml](example_brock.yml).\n\nThe configuration files are merged together, the highest priority config file\nis the one in the current directory. Individual config files don't have to be\ncomplete, however, the merged configuration must contain all required\nparameters.\n\nThe lowest priority config file determines the base directory which will be\nused as a working directory for the executor (e.g. mounted to docker, mounted\nover SSH). The commands should not access files outside this directory.\n\nThe list of all available commands is provided by `brock --help`, let's assume\na command `test` was defined in the `.brock.yml`, you can run it like this:\n```shell\n$ brock test\n>> Executor not running -> starting\n>> Pulling image python:3.9\n./debug/test -s\n\nUnity test run 1 of 1\n\n-----------------------\n483 Tests 0 Failures 0 Ignored\nOK\n```\n\nIf the required executor is not running, it is started automatically when\nexecuting a command. It stays running until it is explicitly stopped by\n`brock --stop`. The executors can also be restarted (e.g. to fetch changes in\nthe brock configuration) by `brock --restart`. The current state of the\nexecutors is printed by `brock --status`.\n\nThe docker image can be pulled again or rebuilt (if using Dockerfile) using\n`brock --update`.\n\nIf needed, you can launch a custom command directly in the executor by\n`brock exec`:\n```shell\n$ brock exec @python 'python --version'\nPython 3.9.10\n```\n\nOptionally, quotes or double-dash (`--`) can be used to avoid brock collecting\noptions destined to the command launched by executor:\n```shell\n$ brock exec @python \"python --version\"\nPython 3.9.10\n$ brock exec @python -- python --version\nPython 3.9.10\n\nIf using a custom Docker registry, do not forget to login into the registry\nbefore using `brock` - use full registry path including image name and tag:\n```shell\n$ docker login $IMAGE_REGISTRY\nUsername: $USER_NAME\nPassword:\nLogin Succeeded\n```\n\nIf using Docker executor, you can launch a shell using `brock shell` (default\nexecutor will be used if ommited):\n```shell\n$ brock shell @gcc\nroot@6bf119cb7b6a:/host# exit\nexit\n```\n\nBrock sets the following predefined environmental variables:\n- `BROCK_HOST_PATH` - absolute path to current directory on host\n- `BROCK_HOST_PROJECT_PATH` - absolute path to project root on host\n- `BROCK_RELATIVE_PATH` - relative path from project root to current directory\n\nAdditional variables can be set using the config option `env` for each executor.\n\n#### Options\nBrock offers the possibility of options in commands.\nConfiguration of options in .brock.yaml (see example_brock.yml)\n\nopt-name:\n- flag: str | None -> option is a flag e.g. `brock build --verbose`\n\n- argument: str | None -> option is an argument e.g. `brock build something`,\ncan be * then an unlimited number of arguments is accepted\n\n- default: any | None -> any value\n\n- choice: list[str] -> list of acceptable values, brock checks input is in choice and also displays it in help\n\n- variable: str | None -> optional custom name of the variable inside the session, to avoid any conflicts with built-in variables\n\n- help: str | None\n\n\n### Isolation types\nThe Brock can detect Windows version and the version of the Windows Docker\nimage, the needed isolation mode is determined automatically - if possible,\nthe image is started in `process` isolation, `hyperv` is used otherwise.\n\n### Volume synchronization\nTo achieve satisfactory performance when using Linux containers on Windows\n(or macOS), the project folder needs to be mounted more efficiently. For this\npurpose, two volume synchronization mechanisms are available: Rsync or Mutagen.\n\n#### Rsync\nAn additional container with Rsync is started - the project folder is mounted to\nthis container together with a named volume (that will reside inside the Linux\nhost) and these folders are then being synced using Rsync. To turn this feature\non, use the `sync` option in the config file.\n\nOptionally, specific files/folders can be excluded from sync using\nconfiguration option `exclude` under `sync` section.\n\n#### Mutagen\nAnother option to synchronize volumes on macOS or Windows is to use\n[Mutagen Extension](https://mutagen.io/documentation/docker-desktop-extension)\nfor Docker Desktop. Before use, it must be installed first:\n```shell\ndocker extension install mutagenio/docker-desktop-extension:latest\n```\nThen, a cache must be created for each path which should be synchronized. Go to\nDocker Desktop -> Extensions -> Mutagen, click Create Cache and enter the\nproject root path. Finally, configure the executor to use Mutagen\nvolume synchronization (see `example_brock.yml`).\n\n### Devices in Docker executor\nThe docker can use the system devices if passed correctly, however this only\nworks when running a native container - e.g. a Windows container with the same\nsystem version as the Windows host, or a Linux container under a Linux host.\nCheck the `devices` section of the config file.\n\n\n## Build\nPlease first apply all steps in [contributing section](#Contributing).\n\nAfter that you can call build scripts:\n```shell\n$ python build/build.py # builds the package\n```\nYou can find build artifacts in the newly created dist folder.\n\n## Contributing\nHere is a short guide to ease you up contributing.\n\nStart by installing virtual environment package\n```shell\n$ pip install virtualenv\n```\nThen create your own virtual environment\n```shell\n$ virtualenv venv\n```\nNow you should see venv folder in the project structure.\nActivate virtual environment\n```shell\n$ source venv/bin/activate # on linux\n$ venv\\Scripts\\activate.bat # on windows\n```\nAfter that you should see (venv) as prefix to your command line cursor.\nNote you need to repeat activation every time you close the terminal.\n\nTo install the package in development mode call:\n```shell\n$ pip install -e .\n```\nNow you can call Brock directly from the command line and all changes to the\nsource code are instantly applied.\n",
"bugtrack_url": null,
"license": "Copyright (c) 2021 The Python Packaging Authority Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Brock",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://www.benderrobotics.com",
"Issues": "https://github.com/BenderRobotics/brock/issues",
"Repository": "https://github.com/BenderRobotics/brock.git"
},
"split_keywords": [
"build",
" docker",
" toolchain"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fc7482022b58995bf9005a64b87fbd36fee9f4b1777f6c8742c82776e3cc4b39",
"md5": "ec3ee52ce6b841d9932366c07e0c1cbd",
"sha256": "e58dea0a5342abea2a14a293bc8b768ae0df6b66fdc65255e8c13c8c55ef8326"
},
"downloads": -1,
"filename": "brock-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ec3ee52ce6b841d9932366c07e0c1cbd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 25240,
"upload_time": "2024-10-26T07:55:28",
"upload_time_iso_8601": "2024-10-26T07:55:28.924835Z",
"url": "https://files.pythonhosted.org/packages/fc/74/82022b58995bf9005a64b87fbd36fee9f4b1777f6c8742c82776e3cc4b39/brock-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5b293f2d3d4ef4bf9bf706a92af68c180a5254b9cd8d28e8c7faf9d896dad6f4",
"md5": "1649dd27f34197124692fe01afc9d62a",
"sha256": "1dcfa48b0cd35db17ced58545e743c6a6373303987aa7842f2f9e353880e554d"
},
"downloads": -1,
"filename": "brock-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "1649dd27f34197124692fe01afc9d62a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 32010,
"upload_time": "2024-10-26T07:55:30",
"upload_time_iso_8601": "2024-10-26T07:55:30.802778Z",
"url": "https://files.pythonhosted.org/packages/5b/29/3f2d3d4ef4bf9bf706a92af68c180a5254b9cd8d28e8c7faf9d896dad6f4/brock-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-26 07:55:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BenderRobotics",
"github_project": "brock",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "brock"
}
