# caiman
A build system for MicroPython applications.
## Features
- Define named targets for MicroPython sources, third party dependencies, and config resources
- Selectively tag targets for mpy compilation or freezing
- Dependency management using mip with dual install locations for development and deployment
- Maintains a build copy on your development machine for code completion
- Build code deployment to target devices using `mpremote`
## Requirements
- Python 3.9+ for local development
- MicroPython installed and added to `PATH` on your local machine
- MicroPython installed on your target device
## Installation
1. In your development environment, install caiman in a Python virtual environment:
```bash
pip install caiman
```
2. Install a MicroPython port on your development machine.
* If developing on a Mac, you can use brew:
```bash
brew install micropython
```
3. Flash the MicroPython firmware on your target device.
## Initialize a new project
* Installing caiman in your local Python environment will make the `caiman` command available.
* All `caiman` commands are run from the root of your project directory.
* `caiman` is configured using a `caiman.yaml` file in the root of your project.
Run the following command from the root of a new project directory:
```bash
caiman init
```
An interactive prompt will guide you through the setup process.
At the end, a `caiman.yaml` file will be created in the root of your project,
together with a basic directory structure.
Your project directory should look like this:
* `caiman.yaml` the project configuration file with your build targets and project metadata.
* `build` folder. Contains the build copy of your project, together with dependency artifacts and manifest files for your targets. Add this to `.gitignore`!
* `venv/mip-packages`folder which stores local copies of your `mip` installed dependencies for code completion. Add this to `.gitignore` and to your `PYTHONPATH`. This folder will be copied over to the build folder when the build command runs.
* `venv/tools` `mip` installed dependencies for development only. Not deployed to the device.
* `micropython` an example folder for your MicroPython source target. You can rename this folder from `caiman.yaml` or define additional source targets. Add this to `PYTHONPATH` for code completion.
## Building your entire project
To build all targets in your project, run the following command from the root of your project:
```bash
caiman build
```
This will copy and selectively compile or freeze all targets defined in your `caiman.yaml` file to the `build` folder.
Nothing is deployed on your device at this point.
The following sections will explain how to define your build targets.
## Defining MicroPython sources
To define a MicroPython source target, add a new entry to your `caiman.yaml` file.
A sample source was created in the `micropython` folder during project initialization.
```yaml
sources:
- name: micropython # the name of the target
parent: micropython # the parent directory of MicroPython sources
frozen: false # whether to tag the target for freezing to firmware (separate firmware build required)
compile: true # whether to compile the target to mpy
files: # paths to component files relative to the parent directory
- '**/*.py'
version: '' # optional - version of the target
```
To build all source targets, run the following command from the root of your project:
```bash
caiman build --target=sources
```
This will copy matching source files from all source targets into the `build/micropython` folder.
Sources tagged for compilation will be compiled to mpy format at this point.
## Defining resources
Any files that are not MicroPython sources can be defined as resources.
These can be config files, images, or other data files that your application needs.
To define a resource target, add a new entry to your `caiman.yaml` file in the `resources` section.
```yaml
resources:
- name: resources # the name of the target
parent: resources # the parent directory of resources
```
The above example will copy all files from the `resources` folder to the `build/micropython` folder.
To build all resource targets, run the following command from the root of your project:
```bash
caiman build --target=resources
```
## Defining dependencies
> A local install of MicroPython is required for dependency management. Make sure it's discoverable on the `PATH`
Dependencies are managed using `mip`, a MicroPython package manager.
They are specified in the `caiman.yaml` file in the `dependencies` section.
Example:
```yaml
dependencies:
- name: logging
version: latest
frozen: false # whether to tag the target for freezing to firmware (separate firmware build required)
compile: true # whether to compile the target to mpy. Local install is always not compiled.
```
This example will install the `logging` package from the MicroPython package index.
To install all dependencies, run the following command from the root of your project:
```bash
caiman build --target=dependencies
```
You can also define specific files that you want to fetch from a dependency.
Example:
```yaml
dependencies:
- name: github:T0ha/uprotobuf
version: main
files:
- protobuf/uprotobuf.py
```
This will only install the specified files from the `uprotobuf` github repository.
## Defining tools
Tools are dependencies that are only required for development and are not deployed to the device.
They are specified in the `caiman.yaml` file in the `tools` section.
You can use parts of a dependency for development only by specifying the files you need.
Example:
```yaml
tools:
- name: github:T0ha/uprotobuf
version: main
compile: false
files:
- scripts/uprotobuf_plugin.py
```
Building all tools:
```bash
caiman build --target=tools
```
This command will copy the specified files from the dependency to the `venv/tools` folder.
## Deploying to the device
> Ensure your device is connected via USB and is discoverable: `ls -latr /dev | grep tty.usbmodem` on OSX.
> Ensure no other processes are using the serial port when deploying to the device. This includes any IDE plugins.
The deployment operation copies the contents of `build/micropython` to the target device.
To deploy all targets, run the following command from the root of your project:
```bash
caiman deploy
```
## Device Operations
### List files on the device
```bash
caiman walk --target=/
```
### Remove all files from the device
> *WARNING*: This will remove all files from the device!
```bash
caiman rmtree --target=/
```
### Dump file contents to the console
```bash
caiman cat --target=/boot.py
```
To do this without logging (useful for parsing):
```bash
caiman --silent cat --target=/boot.py
```
### Run a file on the device
```bash
caiman run --target=boot
```
Raw data
{
"_id": null,
"home_page": "https://github.com/andreicsp/caiman",
"name": "caiman",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Andrei Dumitrache",
"author_email": "andrei@dumitrache.net",
"download_url": "https://files.pythonhosted.org/packages/53/e6/04719c5f46c5773d6c7af2bec5957890989734f438a13a03895ce9c4d124/caiman-0.1.0.tar.gz",
"platform": null,
"description": "# caiman\n\nA build system for MicroPython applications.\n\n\n## Features\n- Define named targets for MicroPython sources, third party dependencies, and config resources\n- Selectively tag targets for mpy compilation or freezing\n- Dependency management using mip with dual install locations for development and deployment\n- Maintains a build copy on your development machine for code completion\n- Build code deployment to target devices using `mpremote`\n\n## Requirements\n- Python 3.9+ for local development\n- MicroPython installed and added to `PATH` on your local machine \n- MicroPython installed on your target device\n\n## Installation\n1. In your development environment, install caiman in a Python virtual environment:\n \n ```bash\n pip install caiman\n ```\n\n2. Install a MicroPython port on your development machine. \n * If developing on a Mac, you can use brew:\n \n ```bash\n brew install micropython\n ```\n \n3. Flash the MicroPython firmware on your target device.\n\n## Initialize a new project\n\n* Installing caiman in your local Python environment will make the `caiman` command available.\n* All `caiman` commands are run from the root of your project directory.\n* `caiman` is configured using a `caiman.yaml` file in the root of your project. \n\nRun the following command from the root of a new project directory:\n\n```bash\ncaiman init\n```\nAn interactive prompt will guide you through the setup process.\nAt the end, a `caiman.yaml` file will be created in the root of your project, \ntogether with a basic directory structure.\n\nYour project directory should look like this:\n\n* `caiman.yaml` the project configuration file with your build targets and project metadata.\n* `build` folder. Contains the build copy of your project, together with dependency artifacts and manifest files for your targets. Add this to `.gitignore`!\n* `venv/mip-packages`folder which stores local copies of your `mip` installed dependencies for code completion. Add this to `.gitignore` and to your `PYTHONPATH`. This folder will be copied over to the build folder when the build command runs.\n* `venv/tools` `mip` installed dependencies for development only. Not deployed to the device. \n* `micropython` an example folder for your MicroPython source target. You can rename this folder from `caiman.yaml` or define additional source targets. Add this to `PYTHONPATH` for code completion.\n\n## Building your entire project\nTo build all targets in your project, run the following command from the root of your project:\n\n```bash\ncaiman build\n```\n\nThis will copy and selectively compile or freeze all targets defined in your `caiman.yaml` file to the `build` folder.\nNothing is deployed on your device at this point.\n\nThe following sections will explain how to define your build targets.\n\n## Defining MicroPython sources\n\nTo define a MicroPython source target, add a new entry to your `caiman.yaml` file.\nA sample source was created in the `micropython` folder during project initialization.\n\n```yaml\nsources:\n- name: micropython # the name of the target\n parent: micropython # the parent directory of MicroPython sources\n frozen: false # whether to tag the target for freezing to firmware (separate firmware build required)\n compile: true # whether to compile the target to mpy\n files: # paths to component files relative to the parent directory\n - '**/*.py'\n version: '' # optional - version of the target\n```\n\nTo build all source targets, run the following command from the root of your project:\n\n```bash\ncaiman build --target=sources\n```\n\nThis will copy matching source files from all source targets into the `build/micropython` folder.\nSources tagged for compilation will be compiled to mpy format at this point.\n\n## Defining resources\n\nAny files that are not MicroPython sources can be defined as resources.\nThese can be config files, images, or other data files that your application needs.\n\nTo define a resource target, add a new entry to your `caiman.yaml` file in the `resources` section.\n\n```yaml\nresources:\n- name: resources # the name of the target\n parent: resources # the parent directory of resources\n```\nThe above example will copy all files from the `resources` folder to the `build/micropython` folder.\n\nTo build all resource targets, run the following command from the root of your project:\n\n```bash\ncaiman build --target=resources\n```\n\n## Defining dependencies\n\n> A local install of MicroPython is required for dependency management. Make sure it's discoverable on the `PATH`\n\nDependencies are managed using `mip`, a MicroPython package manager.\nThey are specified in the `caiman.yaml` file in the `dependencies` section.\n\nExample:\n```yaml\ndependencies:\n- name: logging\n version: latest\n frozen: false # whether to tag the target for freezing to firmware (separate firmware build required)\n compile: true # whether to compile the target to mpy. Local install is always not compiled.\n```\n\nThis example will install the `logging` package from the MicroPython package index.\n\nTo install all dependencies, run the following command from the root of your project:\n\n```bash\ncaiman build --target=dependencies\n```\n\nYou can also define specific files that you want to fetch from a dependency.\n\nExample:\n\n```yaml\ndependencies:\n - name: github:T0ha/uprotobuf\n version: main\n files:\n - protobuf/uprotobuf.py\n```\n\nThis will only install the specified files from the `uprotobuf` github repository.\n\n## Defining tools\n\nTools are dependencies that are only required for development and are not deployed to the device.\nThey are specified in the `caiman.yaml` file in the `tools` section.\nYou can use parts of a dependency for development only by specifying the files you need.\n\nExample:\n```yaml\ntools:\n - name: github:T0ha/uprotobuf\n version: main\n compile: false\n files:\n - scripts/uprotobuf_plugin.py\n```\n\nBuilding all tools:\n\n```bash\ncaiman build --target=tools\n```\n\nThis command will copy the specified files from the dependency to the `venv/tools` folder.\n\n## Deploying to the device\n\n> Ensure your device is connected via USB and is discoverable: `ls -latr /dev | grep tty.usbmodem` on OSX.\n\n> Ensure no other processes are using the serial port when deploying to the device. This includes any IDE plugins.\n\n\nThe deployment operation copies the contents of `build/micropython` to the target device.\n\nTo deploy all targets, run the following command from the root of your project:\n\n```bash\ncaiman deploy\n```\n\n## Device Operations\n\n### List files on the device\n\n```bash\ncaiman walk --target=/\n```\n\n### Remove all files from the device\n\n> *WARNING*: This will remove all files from the device!\n\n```bash\ncaiman rmtree --target=/\n```\n\n### Dump file contents to the console\n\n```bash\ncaiman cat --target=/boot.py\n```\n\nTo do this without logging (useful for parsing):\n\n```bash\ncaiman --silent cat --target=/boot.py\n```\n\n### Run a file on the device\n\n```bash\ncaiman run --target=boot\n```",
"bugtrack_url": null,
"license": "MIT",
"summary": "A build system for MicroPython projects",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/andreicsp/caiman",
"Repository": "https://github.com/andreicsp/caiman"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0ac18488c9199379c3d5fa9f7e3dd221d8b3bc5f4520722a9c8f11d4f20e66bf",
"md5": "a80d9a045f855643045158bba537fe47",
"sha256": "70e59aa4354dce2633a043c382928b9f821752becb5e1d6396c653b22374748e"
},
"downloads": -1,
"filename": "caiman-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a80d9a045f855643045158bba537fe47",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 27780,
"upload_time": "2024-11-23T08:35:57",
"upload_time_iso_8601": "2024-11-23T08:35:57.217583Z",
"url": "https://files.pythonhosted.org/packages/0a/c1/8488c9199379c3d5fa9f7e3dd221d8b3bc5f4520722a9c8f11d4f20e66bf/caiman-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "53e604719c5f46c5773d6c7af2bec5957890989734f438a13a03895ce9c4d124",
"md5": "bf6d37d5f66ce2a924c0660ccacf15e0",
"sha256": "ed229ca268e9f9a532697a263d4aafc3ea356ee85ef067134661c9de7fe03eda"
},
"downloads": -1,
"filename": "caiman-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "bf6d37d5f66ce2a924c0660ccacf15e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 22055,
"upload_time": "2024-11-23T08:35:59",
"upload_time_iso_8601": "2024-11-23T08:35:59.325585Z",
"url": "https://files.pythonhosted.org/packages/53/e6/04719c5f46c5773d6c7af2bec5957890989734f438a13a03895ce9c4d124/caiman-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-23 08:35:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "andreicsp",
"github_project": "caiman",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "caiman"
}
JSON
