diff --git a/CHANGELOG.md b/CHANGELOG.md index 50d5d33..b9355bc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -273,7 +273,7 @@ - Changed: make `platformio_ini_is_patched` a property instead of function - Changed: improved in-code docs -## ver 2.0.0 +## ver 2.0.0 (28.10.20) - New: introducing CI/CD via Azure Pipelines. I tried to make as "general" system as possible with isolated environments, reproducible builds, etc. Due to a number of such a different tools in use and scattered infrastructure around them this task is very complex and the current configuration is far from ideal though - New: new project structure. All packages (core, CLI, GUI) are consolidated under the common `stm32pio` Python _namespace_ - New: app version is completely removed from the repo and is "computed" at build-time from the VCS (GIT) current tag (using [setuptools_scm](https://github.com/pypa/setuptools_scm)). At run-time the version obtaining process depends: for newer Python it can be retrieved from a package metadata, for older one there is an auto-generated `version.py` file with a value stored in it @@ -294,3 +294,44 @@ - Changed: remove board absence warning in `Stm32pio` constructor (this should be done outside) - Changed: take out to the `settings.py` a strings that we looked for to determine successful CubeMX code generation - Changed: use newer `platformio project init` command, use verbose versions of CLI arguments + +## ver 2.1.0 + - New: "validate environment" API. Allows to quickly verify tools specified in the config (+ corresponding test). Currently, implemented only for the CLI version + - New: store the most recent exception in the `last_error` config file parameter (currently CLI-only) (+ corresponding test) + - New: add shorthands for all CLI options (single-letters, e.g. `-c/--with-build`) + - New: ignore list settings API: specify files/folders/patterns to ignore during the cleanup (hence, new `clean()` method, tests) + - New: alternatively, use `git clean` as a removal tool + - New: API to store the current project folder' content as ignore list in the config file + - New: CONTRIBUTING.md guide (more like developing notes actually) + - New: COMMANDS.md reference + - New: CONFIG.md reference + - New: project config reference (a little too many parameters now) + - New: Python 3.9 CI runner + - New: log when the config is merging with another one (DEBUG verbosity level) + - New: handle filenames with whitespaces (both tools/project files) (#21) + - Fixed: `clean()` method doesn't look for the determined `.ioc` file but does it by itself which can cause some unwanted behavior (potential data loss) + - Fixed: remove done/forgotten TODOs + - Fixed: update embedding example to match the current API + - Fixed: `setup.cfg`: specify supported PySide2 version + - Fixed: `setup.cfg`: PyPA parsing issues + - Fixed: revert default CubeMX paths that seems more widespread among users + - Fixed: GUI. Recursive layout warning in Settings window + - Fixed: GUI. Remove the `ProjectID` parameter for the `initialized` signal to get rid of the annoying Shiboken overflow error + - Changed: bump up CubeMX, packages, test `.ioc` file, PlatformIO versions (both for local and CI builds) + - Changed: a completely revised documentation/examples/TODOs structure + - Changed: spawn project-state-related code to the `state.py` module + - Changed: spawn logging-related code to the `logging.py` module + - Changed: separate config from the main class (new `config.py` module) + - Changed: rename `lib.py` -> `project.py` module + - Changed: move available config "None" options to the `settings` module (`none_options`) + - Changed: separate CubeMX invoking code (new project's private `_cubemx_execute_script()` method) + - Changed: edit output behavior in case of occurred error in the `generate_code()` function + - Changed: do not cast strings where we can use path-like objects + - Changed: pretty config printer (`__str__()` implementation, just `print(project.config)`, that's all) + - Changed: remove `util.configparser_to_dict()` function (`ConfigParser` is already conforms with mapping protocol) + - Changed: takeout valid user response options to `settings.py` (`yes_options`/`no_options`) + - Changed: group and move CI-related code in the `settings.py` + - Changed: remove `f"{STAGE_PATH.name}.ioc"` occurrences in tests + - Changed: move `test_clean()` to unit tests + - Changed: GUI. Remove `go_to_this` option for the `addListItem` method (instead invoke on the list model) + - Changed: GUI. Implicitly pass the parent to the project constructor in `addListItem` method diff --git a/CI/lockfile.yml b/CI/lockfile.yml index 56652d0..73c3a37 100644 --- a/CI/lockfile.yml +++ b/CI/lockfile.yml @@ -5,9 +5,9 @@ # to have them all in one place (especially because they are all make sense mostly for the testing/CI purposes) variables: - cubemx_version: 601 # 6.0.1 + cubemx_version: 611 # 6.1.1 # we should store nothing but strings for variables values so we encapsulate YAML into string - cubemx_packages: "f0: 1.11.1" - platformio_version: 5.0.1 + cubemx_packages: "f0: 1.11.2" + platformio_version: 5.0.3 test_cases: | - nucleo_f031k6 diff --git a/CI/setup_test_env.py b/CI/setup_test_env.py index f379bd0..d143b6f 100644 --- a/CI/setup_test_env.py +++ b/CI/setup_test_env.py @@ -20,7 +20,7 @@ def install_cubemx_mcu_packages(query): cubemx_script_content = '\n'.join([f"swmgr install stm32cube_{series}_{version} accept" for series, version in query.items()]) + "\nexit" cubemx_script.write(cubemx_script_content.encode()) # encode since mode='w+b' - subprocess.run(['java', '-jar', str(Path(os.getenv('STM32PIO_CUBEMX_CACHE_FOLDER')) / 'STM32CubeMX.exe'), '-q', + subprocess.run(['java', '-jar', Path(os.getenv('STM32PIO_CUBEMX_CACHE_FOLDER')) / 'STM32CubeMX.exe', '-q', cubemx_script_name, '-s']) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..75a0290 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,44 @@ +# Developing & contributing +Find actual tasks at [TODO.md list](/TODO.md) / [GitHub issues](https://github.com/ussserrr/stm32pio/issues). This file focuses on some relevant topics regarding build/test/CI processes. The code is well commented in-place and that can be considered as a developer documentation really. Some parts also can be found in the [docs](/docs) folder. + + +## Build +Staring from v2.0.0, the PEP517-compatible build process is supported. This process, yet described and standardized in several PEPs, is still a pretty early one and not fully adopted by official Python tools (such as pip, twine), though (at the time of publication at least). So the current way to pack is a little messy and relies on different instruments. Better use the latest Python and build packages versions. + +For the dependencies list see [pyproject.toml](/pyproject.toml) file: +```shell script +$ pip install wheel setuptools setuptools_scm +``` + +To build a Python _wheel_ `setup.py` is not even required: +```shell script +$ pip wheel . --wheel-dir dist +``` +but for the assembling of the source distribution tarball it is still necessary: +```shell script +$ python setup.py sdist +``` + + +## Test +Testing (code is located at the [`tests`](/tests) directory) is done via the `unittest` module from the Python standard library. It's compatible with the `pytest` runner, too. Single test stage is a CubeMX project (`.ioc` file). Several such targets can be placed inside the `fixtures` folder to test against. Then start testing specifying concrete fixture as an environment variable: +```shell script +stm32pio-repo/ $ STM32PIO_TEST_CASE=nucleo_f031k6 python -m unittest -b -v +``` +Every run automatically instantiates a temporary directory (using `tempfile` module) where all the actions are performed so no repository file will be "disturbed". To run the specific group of tests or a particular test function you can use: +```shell script +stm32pio-repo/ $ python -m unittest tests.test_integration.TestIntegration +stm32pio-repo/ $ python -m unittest tests.test_cli.TestCLI.test_verbosity +``` +`.ioc` files and installed tools' versions should match otherwise the CubeMX will complain about their incompatibility. + + +## CI/CD +Azure Pipelines is used to automate test, build, and publish tasks (see [azure-pipelines.yml](/azure-pipelines.yml), [CI](/CI) for more information). The repo is tested against the matrix of all 3 major OSes and latest Python interpreters. Also, for the Linux runs the test percentage and coverage are calculated. Therefore, for these purposes some additional external dependencies are required: + - pytest + - coverage + - yaml + +There are some elements of the "reproducible builds" approach using several "lockfiles", isolated test fixtures and caching. Optional `platformio.ini.lockfile`, "freezing" the PlatformIO packages' versions needed for a successful build, can be placed inside an every fixture folder. This config is an ordinary .INI-style file which will be merged into the `platformio.ini` during testing. + +Overall, due to a number of such a diverse tools in use, the full-fledged "canonical" CI seems challenging to implement, and the current set up is far from ideal in that regard. diff --git a/README.md b/README.md index 7294382..6ae0cf0 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ # stm32pio -[![Build Status](https://dev.azure.com/andrei42008/stm32pio/_apis/build/status/ussserrr.stm32pio?branchName=dev)](https://dev.azure.com/andrei42008/stm32pio/_build/latest?definitionId=1&branchName=dev) +[![Build Status](https://dev.azure.com/andrei42008/stm32pio/_apis/build/status/ussserrr.stm32pio?branchName=master)](https://dev.azure.com/andrei42008/stm32pio/_build/latest?definitionId=1&branchName=master) -Small cross-platform Python app that can create and update [PlatformIO](https://platformio.org) projects from the [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html) `.ioc` files. +Small cross-platform Python app that can create and update [PlatformIO](https://platformio.org) projects from [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html) `.ioc` files. -It uses STM32CubeMX to generate a HAL-framework-based code and alongside creates PlatformIO project with the compatible parameters to stick them both together. +It uses the STM32CubeMX to generate a HAL-framework-based code and alongside creates the PlatformIO project with compatible parameters to bind them both together. -The [GUI version](/docs/gui/README.md) is available, too. +The [GUI version](/docs/GUI/README.md) is available, too (please, read this main introduction first). -![Logo](/screenshots/logo.png) +![Logo](/logo/logo.png) ## Table of contents @@ -16,54 +16,43 @@ The [GUI version](/docs/gui/README.md) is available, too. > - [Requirements](#requirements) > - [Installation](#installation) > - [Usage](#usage) -> - [Project patching](#project-patching) -> - [Embedding](#embedding) -> - [Example](#example) -> - [Build](#build) -> - [Test](#test) -> - [CI](#ci) +> - [Troubleshooting](#troubleshooting) > - [Restrictions](#restrictions) ## Features - - Start the new complete project in a single directory using only an `.ioc` file - - Update an existing project after changing a hardware options in CubeMX + - Originate the new full-fledged project in a single directory starting only from an `.ioc` file + - Seamlessly update an existing project after the hardware changes by CubeMX + - Quickly check the current state + - Inspect tools (CubeMX, PlatformIO, etc.) - Clean-up the project - - Get the status information - - *[optional]* Automatically run your favorite editor in the end - - *[optional]* Automatically make an initial build of the project - - *[optional]* GUI version (see [the dedicated README](/docs/gui/README.md) file) + - *[optional]* Automatically run your favorite editor or initiate a build in the end + - *[optional]* GUI edition (see [the dedicated README](/docs/GUI/README.md) file) (please, read this main introduction first) ## Requirements: -The app presents zero dependencies by itself and requires only this to run: - - macOS, Linux, Windows - - Python 3.6 and above +**OS:** macOS, Linux, Windows 7-10 -Of course, you need to have all the necessary tools to be installed in order to work with them: - - STM32CubeMX with the desired downloaded frameworks (F0, F1, etc.). All recent versions are fine, probably something like 5.0+ - - Java CLI (JRE, Java runtime environment) for the CubeMX (likely is already installed if the CubeMX is working). In other words, you should be able to launch the Java from your terminal using `java` command. Which version is appropriate for the CubeMX you can find in its docs - - PlatformIO (4.2.0 and above) CLI (already present if you have installed PlatformIO via some package manager (`pip`, `apt`, `brew`, etc.) or need to be installed as the "command line extension" from IDE (see [docs](https://docs.platformio.org/en/latest/core/installation.html) for more information)) +**Python:** 3.6+ -If you for some reasons don't want to or cannot install command line versions of these applications in your system you can always specify the direct paths to them using the project configuration file `stm32pio.ini` or even override the default values in the source code file `core/settings.py`. +The app introduces zero dependencies by itself. Of course, you need to have all the necessary tools installed in order to perform the operations: + - STM32CubeMX with the desired downloaded frameworks (F0, F1, etc.). All recent versions are fine (5.x, 6.x) + - Java (JRE, Java runtime environment) for the CubeMX (already installed if the CubeMX is working). Which version is appropriate for the CubeMX you can find in its own description + - PlatformIO (4.2.0 and above) CLI (most likely is already present if you have installed it via some package manager (`pip`, `apt`, `brew`, etc.) or need to be installed as a "command line extension" from the PlatformIO IDE (see its [docs](https://docs.platformio.org/en/latest/core/installation.html#piocore-install-shell-commands) for more information)) -Also, some external dependencies may be required to build, test and pack the app. See the corresponding sections for more information. - -A general recommendation there would be to test both CubeMX (code generation) and PlatformIO (project creation, building) at least once before using the stm32pio to make sure all the tools work properly even without any "glue". - -**2020 Update**: in my tests, recent versions of CubeMX had been shipping with no installer of some sort. So I just unpack the distribution archive and place it in `~/cubemx` directory so it can be started simply as `java -jar ~/cubemx/STM32CubeMX.exe`. That's why the default path is as mentioned above. Tell me if your default path is rather another. Also, the default structure of the generated code is significantly different when you invoke the generation from the GUI version of CubeMX or the CLI one. As stm32pio uses the latter, currently the PlatformIO project structure cannot be properly patched to use a code from the GUI version of CubeMX (at least with the default patch config, you can always tweak it in a configuration file `stm32pio.ini`). +If you, for some reasons, don't want to (or simply cannot) install (i.e. register in PATH) command line versions of these applications in your system, you can always specify the direct paths to them overriding the default values in the project configuration file `stm32pio.ini`. Check the [config reference](/docs/CONFIG.md) to see all possible ways of telling stm32pio where the tools are residing on your machine. ## Installation -As a normal Python package the app can be run in a completely portable way by downloading or cloning the snapshot of this repository and invoking the main script (or the Python module): +As a normal Python package the app can be run in a completely portable way by downloading (or cloning) the snapshot of this repository and invoking the main script: ```shell script -stm32pio-repo/ $ python3 stm32pio/cli/app.py # or -stm32pio-repo/ $ python3 -m stm32pio.cli # or +stm32pio-repo/ $ python3 stm32pio/cli/app.py +stm32pio-repo/ $ python3 -m stm32pio.cli # or as the Python module any-path/ $ python3 path/to/stm32pio-repo/stm32pio/cli/app.py ``` -(we assume `python3` and `pip3` hereinafter). +Note: we will assume `python3` and `pip3` hereinafter. -However, it's handier to install the utility to be able to run stm32pio from anywhere. The PyPI distribution (starting from v0.95) is available: +However, it's handier to install the utility to be able to run from anywhere. The PyPI distribution is available: ```shell script $ pip install stm32pio ``` @@ -75,112 +64,46 @@ $ pip uninstall stm32pio ## Usage -Basically, you need to follow such a pattern: - 1. Create CubeMX project (`.ioc` file), set-up your hardware configuration, save with the compatible parameters - 2. Run the stm32pio that automatically invokes CubeMX to generate the code, creates PlatformIO project, patches a `platformio.ini` file and so on - 3. Work with your project normally as you wish, compile/upload/debug etc. - 4. Come back to the hardware configuration in CubeMX when necessary, then run stm32pio to re-generate the code - -Refer to Example section on more detailed steps. If you face off with some error try to enable a verbose output to get more information about a problem: -```shell script -$ stm32pio -v [command] [options] -``` - -On the first run stm32pio will create a config file `stm32pio.ini`, syntax of which is similar to the `platformio.ini`. You can also create this config without any following operations by initializing the project: -```shell script -$ stm32pio init -d path/to/project -``` -It may be useful to tweak some parameters before proceeding. The structure of the config is separated into two sections: `app` and `project`. Options of the first one is related to the global settings (such as commands to invoke different instruments) though they can be adjusted on the per-project base while the second section contains of project-related parameters. See comments in the [`settings.py`](/stm32pio/core/settings.py) file for parameters description. - You can always run ```shell script $ stm32pio --help ``` -to see help on available commands. Find the copy of its output on the [project wiki](https://github.com/ussserrr/stm32pio/wiki/stm32pio-help) page, also. +to see help on available commands. -### Project patching +Basically, you need to follow such a workflow (refer to the [example](/examples/cli) which explains the same just illustrating it with some screenshots/command snippets): + 1. Create the CubeMX project (`.ioc` file) like you're used to, set up your hardware configuration, but after all save it with the compatible parameters + 2. Run stm32pio that automatically invokes CubeMX to generate a code, creates the PlatformIO project, patches the `platformio.ini` file. + 3. Work with your project normally as you wish, build/upload/debug etc. + 4. When necessary, come back to the hardware configuration in the CubeMX, then run stm32pio again to re-generate the code -Note, that the patch operation (which takes the CubeMX code and PlatformIO project to the compliance) erases all the comments (lines starting with `;`) inside the `platformio.ini` file. They are not required anyway, in general, but if you need them for some reason please consider saving the information somewhere else. - -For those who wants to modify the patch (default one is at [`settings.py`](/stm32pio/core/settings.py), project one in a config file `stm32pio.ini`): it has a general-form .INI-style content so it's possible to specify several sections and apply composite patches. This works totally fine for the most cases except, perhaps, some really big complex patches involving, say, the parameters interpolation feature. It is turned off for both `platformio.ini` and user's patch parsing by default. If there are some problems you've met due to a such behavior please modify the source code to match the parameters interpolation kind for the configs you need to. Seems like `platformio.ini` uses `ExtendedInterpolation` for its needs, by the way. - -### Embedding - -You can also use stm32pio as an ordinary Python package and embed it in your own application. Find the minimal example at the [examples](/examples) to see some possible ways of implementing this. Basically, you need to import `stm32pio.core.lib` module (where the main `Stm32pio` class resides), _optionally_ set up a logger and you are good to go. If you prefer higher-level API similar to the CLI version, use `main()` function in `cli/app.py` passing the same CLI arguments to it. Also, take a look at the CLI ([`app.py`](/stm32pio/cli/app.py)) or GUI versions. - - -## Example -1. Run CubeMX, choose MCU/board, do all necessary tweaking -2. Select `Project Manager -> Project` tab, specify "Project Name", choose "Other Toolchains (GPDSC)". In `Code Generator` tab check "Copy only the necessary library files" and "Generate periphery initialization as a pair of '.c/.h' files per peripheral" options - -![Code Generator tab](/docs/cubemx_project_settings/tab_CodeGenerator.png) - -3. Back in the first tab (Project) copy the "Toolchain Folder Location" string (you may not be able to copy it in modern CubeMX versions so use a terminal or a file manager to do this). Save the project +See the [commands reference](/docs/CLI/COMMANDS.md) file listing the complete help about the available commands/options. On the first run, stm32pio will create a config file `stm32pio.ini`, syntax of which is similar to the `platformio.ini`. You can also create this config without any following operations by initializing the project: +```shell script +$ stm32pio init -d path/to/project +``` +It may be useful to tweak some parameters before proceeding. See the [config reference](/docs/CONFIG.md) showing meanings for every key. -![Project tab](/docs/cubemx_project_settings/tab_Project.png) -4. Use a copied string (project folder) as a `-d` argument for stm32pio (can be omitted if your current working directory is already a project directory). -5. Run `platformio boards` (`pio boards`) or go to [boards](https://docs.platformio.org/en/latest/boards) to list all supported devices. Pick one and use its ID as a `-b` argument (for example, `nucleo_f031k6`) -6. All done! You can now run +## Troubleshooting +If you're stuck and the basic logs doesn't clear the situation, try the following: + - Run the same command in the verbose mode using the `-v` key: ```shell script - $ stm32pio new -d path/to/cubemx/project/ -b nucleo_f031k6 --start-editor=code --with-build + $ stm32pio -v [command] [options] ``` - to trigger the code generation, compile the project and start the VSCode editor with opened folder (last 2 options are given as an example and they are not required). Make sure you have all the tools in PATH (`java` (or set its path in `stm32pio.ini`), `platformio`, `python`, editor). You can use a slightly shorter form if you are already located in the project directory: + This will unlock additional logs which might help to clarify + - Validate your environment, i.e. check whether the stm32pio can find all the essential tools on your machine: ```shell script - path/to/cubemx/project/ $ stm32pio new -b nucleo_f031k6 + $ stm32pio validate -d path/to/project ``` -7. To get the information about the current state of the project use `status` command. -8. If you will be in need to update the hardware configuration in a future, make all the necessary stuff in CubeMX and run `generate` command in a similar way: + This will print the report about the current set up according to your config `stm32pio.ini` file. + - Use the dynamic help feature which outputs information specifically about the requested command, e.g.: ```shell script - $ stm32pio generate -d /path/to/cubemx/project + $ stm32pio new -h ``` -9. To clean-up the folder and keep only the `.ioc` file run `clean` command. - - -## Build -Staring from v2.0.0 PEP517-compatible build process is supported. For the build dependencies list see [pyproject.toml](/pyproject.toml) file: -```shell script -$ pip install wheel -$ pip install setuptools setuptools_scm -``` -This process yet described and standardized in PEPs is still early and not fully implemented by the different tools (such as pip, twine) though (at the time of this version at least). So the current way is a little bit messy and depends on different instruments. Use the latest Python and build packages versions. To build a _wheel_ `setup.py` is not even required: -```shell script -$ pip wheel . --wheel-dir dist -``` -but for the source distribution tarball it is still necessary: -```shell script -$ python setup.py sdist -``` - - -## Test -There are some tests in [`tests`](/tests) directory (based on the unittest module). The test stage is a CubeMX project (`.ioc` file) with an optional `platformio.ini.lockfile` config specifying the versions of the used ("locked") PlatformIO libraries (see "CI" chapter) (this config is an ordinary .INI-style file which will be merged with the `platformio.ini` test file). Several such targets can be placed to the `fixtures` folder to test against. Finally, run this command setting the current case as an environment variable -```shell script -stm32pio-repo/ $ STM32PIO_TEST_CASE=nucleo_f031k6 python -m unittest -b -v -``` -to test the stm32pio. Tests code automatically create temporary directory (using `tempfile` Python standard module) where all actions are performed. - -To run the specific group of tests or a single test function you can use: -```shell script -stm32pio-repo/ $ python -m unittest tests.test_integration.TestIntegration -stm32pio-repo/ $ python -m unittest tests.test_cli.TestCLI.test_verbosity -``` - -Automated tests against old `.ioc` files seems not possible because of CubeMX interactive GUI prompts about migrations. I don't find any CLI key or option to disable them (and in general, documentation for the CubeMX CLI doesn't look complete...). - - -## CI -Azure Pipelines is used to automate test, build, and publish tasks. The repo is tested against all 3 major OSes and for the Linux the test coverage is also calculated. For this purposes some additional external dependencies are necessary, such as - - pytest - - coverage - - yaml - -There are some elements of the "reproducible builds" approach using several "lockfiles", isolated test fixtures and caching. Actually, due to a number of different tools in use and their nature the truly and fully "canonical" CI seems challenging to implement so the current system is far from ideal. It probably will be improved in the future, see [azure-pipelines.yml](/azure-pipelines.yml), [CI](/CI) for more information for now. ## Restrictions - - The tool doesn't check for different parameters compatibility, e.g. CPU frequency, memory sizes and so on. It simply eases your workflow with these 2 programs (PlatformIO and STM32CubeMX) a little bit. - - CubeMX middlewares are not supported yet because it's hard to be prepared for every possible configuration. You need to manually adjust them to build appropriately. For example, FreeRTOS can be added via PlatformIO' `lib` feature or be directly compiled in its own directory using `lib_extra_dirs` option: + - The tool doesn't check for different parameters' compatibility, e.g. CPU/IO/etc frequencies, allocated memory and so on. It simply eases your workflow with these 2 programs (PlatformIO and STM32CubeMX) a little bit. + - In order to add CubeMX middlewares to your build the manual adjustments should be applied, the stm32pio doesn't handle them automatically. For example, FreeRTOS can be added via PlatformIO' `lib` feature or be directly compiled in its own directory using `lib_extra_dirs` option: ```ini lib_extra_dirs = Middlewares/Third_Party/FreeRTOS ``` diff --git a/TODO.md b/TODO.md index a21d31f..b7b707a 100644 --- a/TODO.md +++ b/TODO.md @@ -1,34 +1,64 @@ -# TODOs +# TODO list ## Business logic, general features - [ ] GitHub CHANGELOG - separate New, Fixed, Changed into paragraphs - [ ] Middleware support (FreeRTOS, etc.) - [ ] Arduino framework support (needs research to check if it is possible) - [ ] Create VSCode plugin - - [ ] UML diagrams (core, GUI back- and front-ends, thread flows, events, etc.) - - [ ] CI is possible (Arch's AUR has the STM32CubeMX package, also there is a direct link). Deploy Docker one in Azure Pipelines, basic at Travis CI + - [ ] UML diagrams (core, GUI back- and front-ends, thread flows, events, etc.). Maybe automated - [ ] In the future, probably use https://setuptools.readthedocs.io/en/latest/setuptools.html#accessing-data-files-at-runtime `importlib.resources` as a standard API to access non-Python files inside Python packages (such as `.qml`) - [ ] Use some features of newer Pythons after dropping the support for 3.6 (and so on) + - [ ] Generate code docs (help user to understand an internal mechanics, e.g. for embedding). Say, just for public API (main project, `cli.app.main()`, logging). Can be uploaded to the GitHub Wiki. Currently, we struggle to even track the API changes (e.g. for semver). API is some code endpoints and entire CLI set, I suppose... + - [ ] Build, install and only then test the app + - [ ] Remade this TODO list as a GitHub issues/project/milestones. Use labels to mimic DISCUSSION ones and so on (UPD: GitHub now has its own "discussions" feature actually) + - [ ] Write in the README about why we use an INI config format (because it should be familiar to the PlatformIO user). Also consider migrating to some other (more feature-rich) format (JSON, etc.) + - [ ] See on GitHub what people looking for the most (what files) and adjust those parts of the repo + - [ ] Collect all Python 3.7+ TODOs, notes, etc. to form some kind of resume of what can be done to take advantages of new language/lib features while dropping the 3.6 support + - [ ] Implement some _optional_ global config (e.g. `~/.stm32pio`) where the users can specify their paths/commands of tools. Maybe integrate with the validation feature + - [ ] setuptools now migrating to PEP-517 finally, see its docs + - [ ] Check do we actually need `wheel` package to be installed prior `pip install stm32pio`. Can we add it to dependencies and be sure it will be retrieved before any other? + - [ ] Adopt Google style guides (https://google.github.io/styleguide/pyguide.html), or some another one (comments, docstrings, etc.)... + - [ ] Probably still should move docs to GitHub Wiki... + + +## CI + - [ ] Lock ALL tools' versions per a commit! CubeMX F0 framework, PlatformIO and its build tools & libraries versions (use templates, variables and cache). Every build is dependent on: + - PlatformIO + - PlatformIO packages + - CubeMX + - CubeMX packages + - PySide2 + - Python + - Win/Mac/UNIX + - [ ] CI/test-related code in the `settings.py` is probably not good, should find the workaround + - [ ] Fail of not all tests have been passed + - [ ] Templates for CI? + - [ ] Migrate to GitHub actions? + - [ ] Use `setup.cfg` to add CI extra with all its dependencies (pyyaml, pytest, etc.) + ## GUI version + - [ ] Live-reload config file - [ ] Obtain boards on demand (not at the startup) - [ ] Can probably detect Ctrl and Shift clicks without moving the mouse first - [ ] Mac: sometimes auto turned off shift highlighting after action (hide-restore helps) - [ ] Some visual flaws when the window have got resized (e.g. 'Add' button position doesn't change until the list gets focus, 'Log' area crawls onto the status bar) - [ ] Tests (research approaches and patterns) - [ ] Remade the list item to use States, too. Probably, such properties need to be implemented: - ``` - state: { - loaded, + ``` + state: { + - loading (show spinner) + - new (green highlighting) + - cannot be initialized (red highlighting) + - action has finished successfully (green dot) + - action has finished with error (red dot) - visitedAfterInstantiating, + - selected + - not selected - actionRunning, - [+] lastActionStatus, - visitedAfterAction, - ... - } - ``` + ... + } + ``` - [ ] Test with different timings - [ ] Divide on multiple modules (both Python and QML) - [ ] Implement other methods for Qt abstract models @@ -39,40 +69,61 @@ - [ ] Linux: Not a monospaced font in the log area - [ ] Temporarily pin projects with currently running actions to the top (and stay there on scrolling). See QML Package type - [ ] "Pressed" effect for action buttons - - [x] Fix: bold borders remains after an error - [ ] Maybe do not save the stm32pio.ini if there wasn't one (after starting from CLI) - [ ] Specify board without reloading the app. Warn that board is not specified after cleanup + - [ ] Add multiple folders on "Add" button + - [ ] Do not store the state in the list delegate. Save it in the model, also widgets will be using it so the code will be cleaner + - [ ] Setup QML logging proxy (QML's `console.log()` functions family to the Python `logging`) for all platforms (not only Windows) + - [ ] Interface for the validation feature (and other that have been implemented in CLI yet GUI lacks) + ## Core library and CLI - - [ ] when updating the project (`generate` command), check for boards match - - [ ] Remove casts to string where we can use path-like objects (related to a Python version as new ones receives path-like objects arguments while old ones aren't) - - [ ] We look for some snippets of strings in logs and output for the testing code but we hard-code them and this is not good, probably (e.g. 'DEBUG') - - [ ] Store an initial content of the folder in .ini config and ignore it on clean-up process. Allow the user to modify such list (i.e. list of exclusion) in the config file. Mb some integration with `.gitignore` - - [ ] at some point check for all tools (CubeMX, ...) to be present in the system (both CLI and GUI) (global `--check` command (as `--version`), also before execution of the full cycle (no sense to start if some tool doesn't exist)) - - [ ] generate code docs (help user to understand an internal mechanics, e.g. for embedding). Can be uploaded to the GitHub Wiki - - [ ] colored logs, maybe (breaks zero-dependency principle) - - [ ] maybe migrate to async/await approach in the future (return some kind of a "remote controller" to control the running action) - - [ ] `__init__`' `parameters` dict argument schema (Python 3.8 feature). - - [ ] Mb store the last occurred exception traceback in .ini file and show on some CLI command (so we don't necessarily need to turn on the verbose mode and repeat this action). And, in general, we should show the error reason right off - - [ ] the lib sometimes raising, sometimes returning the code and it is not consistent. While the reasons behind such behavior are clear, would be great to always return a result code and raise the exceptions in the outer scope, if there is need to - - [ ] check board (no sense to go further on 'new' if the board in config.ini is not correct) - - [ ] test using virtualenv - - [ ] test for different `.ioc` files (i.e. F0, F1, F4 and so on) as it is not the same actually - - [ ] mb allow to use an arbitrary strings (arrays of str) to specify tools commands in stm32pio.ini (shell=True or a list of args (split a string)) - - [x] cache boards for a small interval of time - - [ ] count another '-v' as '-v' for the PlatformIO calls (as a slider in the GUI settings window) - - [ ] Project' name (path) can be reused so cannot be used as a unique identifier but so is id(self)? Probably it is better to use a path (human-readable) - - [ ] Analyze `.ioc` file for the wrong framework/parameters - - [x] Take out to settings "[ERROR]", "Successful code generation" etc. + +### PlatformIO board + - [ ] When updating the project (`generate` command), check for boards match + - [ ] Check board (no sense to go further on 'new' if the board in the config.ini is not correct) + - [ ] If `--board` has not been supplied, try to get it from the `platformio.ini` (if present) + +### Control spawn subprocesses + - [ ] maybe migrate to async/await approach in the future (return some kind of "remote controller" to control the running action) - [ ] Kill subprocesses if there is no output have appeared for some timeout (i.e. hung) - - [x] Fix when empty '' board string overwrites existing - - [x] Allow to not specify a board for the `new` command when it is already specified in the config - - [ ] Maybe logging notifications about which parameters has superseded which - - [x] Add `patch` command (all other are already present in some way (through `stm32pio` or `pio`)) or another + +### CubeMX - [ ] Use CubeMX options such as `project couplefilesbyip <0|1>` and `project toolchain ` or ... - [ ] ... parse an `.ioc` file and edit the parameters in-place if necessary - - [x] Expand CLI keys and options everywhere (e.g. `--project-option` instead of `-O`) - - [ ] Build, install and only then test the app - - [ ] Templates for CI? - - [ ] Deal with CubeMX requests about software package and CubeMX versions migrations (seems like the only way is to set them in `.ioc` file, no appropriate CLI keys) - - [ ] If `--board` has not been supplied try to get it from the `platformio.ini` (if present) + - [ ] Analyze `.ioc` file for the wrong framework/parameters (validation continues...) + - [ ] Deal with CubeMX requests about software package and CubeMX versions migrations (seems like the only way is to set them first in `.ioc` file, no appropriate CLI keys) + +### Config + - [ ] mb allow to use an arbitrary strings (arrays of str) to specify tools commands in stm32pio.ini (`shell=True` or a list of args (split a string)) + - [ ] Mark some parameters as unnecessary and do not save them to config unless explicitly stated (it can now be implemented more easily thanks to the `Config` subclass, I guess) (some DB-like schema) + - [ ] Store an editor in the config? + +### Tests + - [ ] Closely audit the test suite (e.g. CLI tests doesn't verify ALL available commands because some of them will be considered redundant in the presence of unit tests and so on) + +### Other + - [ ] Remove casts to string where we can use path-like objects (seems like Python 3.6 on Windows is delaying this) + - [ ] DISCUSSION. Colored CLI logs, maybe (3rd-party) (breaks zero-dependency principle though...) + - [ ] `__init__`' `parameters` dict argument schema (Python 3.8 feature). + - [ ] DISCUSSION. The lib sometimes raising, sometimes returning the code and it is not consistent. Current decision-making agent: common sense and the essence of the action. Would be great to always return a result code and raise the exceptions in the outer scope, if there is need to + - [ ] count another `-v` as `-v` for the PlatformIO calls (also we can implement it as a (vertical) slider in the GUI settings window (remember Windows UAC panel?)) + - [ ] DISCUSSION. Project name (path) can be reused so cannot be used as a unique identifier but so is `id(self)`? Probably it is better to use a path (human-readable) (but it also can be reused...) + - [ ] DISCUSSION. Use `--start-editor` as a generic action to perform after the main operation (rename, of course)? + - [ ] Take a look to the `dataclass` feature and find where we can apply it (3.7+) + - [x] DISCUSSION. Support equality comparison for `Project` (`__eq__()`) and get rid of `p1.path.samefile(p2.path)`. It's actually a more complicated topic than it seems, e.g. what are _equal_ projects? Path is not the only component of the project despite being the primary one, what about the config content though? It can be different for the same path at different points of time (when config were read after some period). Not needed at the moment + - [ ] Check with some static analyzer (mypy) (actually, PyCharm is already doing it) + - [x] Test for names with spaces (everywhere) (#21) + - [x] Check `subprocess.PIPE`/`subprocess.DEVNULL` relations + - [ ] Set `git` command in settings (config). There are a little too many options now, should consider hide them unless explicitly set + - [ ] Edit INI config from CLI. NO! This task is "out of scope" for this app and any `set` command will probably be confusing for the user. Just type `editor stm32pio.ini` + - [ ] Public API backward compatibility testing (core lib + CLI, I guess) + - [ ] If we output config "diffs" (in debug mode) we should print them more beautiful (some tables or so). Probably should consider external dependency or optional CLI tool (if present then ...) + - [ ] Project' `instance_options` is kind of ugly... + - [ ] download missing CubeMX software packages (F0, F1, etc.) using temp script + - [ ] what if some parameters missing in the config file? Check the behavior + - [ ] `platformio_ini_is_patched` is actually not so reliable. For example, some property can contain both our and user-defined values and still technically be considered as "patched". Maybe should use `in` for checking instead of the strict equality + - [ ] Be able to set the `platformio_cmd` in config to `python -m platformio` (convert to list and concat where used) + - [x] Add `pio_init` to CLI + - [ ] Automatically add the `stm32pio.ini` and artifacts to git + - [ ] Convert the embedding example to an IPython notebook (or smth like this) diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 08eca5e..11ef9c2 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -1,11 +1,3 @@ -# Python package -# Create and test a Python package on multiple Python versions. -# Add steps that analyze code, save the dist with the build record, publish to a PyPI-compatible index, and more: -# https://docs.microsoft.com/azure/devops/pipelines/languages/python - -# TODO: Lock ALL tools versions per commit! CubeMX F0 framework, PlatformIO and its build tools & libraries versions -# (use templates, variables and cache) - trigger: - master - dev @@ -35,6 +27,8 @@ stages: python.version: '3.7' Python38: python.version: '3.8' + Python39: + python.version: '3.9' steps: - task: UsePythonVersion@0 inputs: @@ -116,6 +110,8 @@ stages: python.version: '3.7' Python38: python.version: '3.8' + Python39: + python.version: '3.9' steps: - task: UsePythonVersion@0 inputs: @@ -179,6 +175,8 @@ stages: python.version: '3.7' Python38: python.version: '3.8' + Python39: + python.version: '3.9' steps: - task: UsePythonVersion@0 inputs: diff --git a/docs/CLI/COMMANDS.md b/docs/CLI/COMMANDS.md new file mode 100644 index 0000000..7780294 --- /dev/null +++ b/docs/CLI/COMMANDS.md @@ -0,0 +1,135 @@ +# CLI API +This file is describing all operations available from the command line interface version of the application. You can also use an applicable to any command `-h/--help` key to refer to its short description at any time. All the commands below can be run in the verbose mode with the `-v/--verbose` key given and will print some additional debug information. It is useful for errors tracking. Please supply the verbose output when submitting an issue/question about the stm32pio. + +## Table of contents +> - [Project life-cycle](#project-life-cycle) +> - [`init`](#init) +> - [`generate`](#generate) +> - [`pio_init`](#pio_init) +> - [`patch`](#patch) +> - [`new`](#new) +> - [Utils](#utils) +> - [`clean`](#clean) +> - [`status`](#status) +> - [`validate`](#validate) +> - [`gui`](#gui) +> - [Options](#options) + + +## Project life-cycle +These commands summarize the stm32pio goal – managing of the project combining STM32CubeMX and PlatformIO. The real-life example can be found [here](/examples/cli), it shows a typical use case (with screenshots). + +### `init` +This will initialize a fresh new project creating `stm32pio.ini` config where you can review and tweak any parameters if necessary. Normally, the latter shouldn't be a case, it is only needed, for example, if tools are installed somewhat different on your machine (e.g. `platformio` is not in the PATH environment variable). +#### Prerequisites +`.ioc` file should be present at the specified path (in fact, this determines what is a project and what isn't). +#### Expected output +✅ `stm32pio.ini` + +### `generate` +This will start the CubeMX for you and tell it to run the code generation against your `.ioc` file. CubeMX has its own CLI mode which is used for this feature. However, it still can prompt or warn you about some things, e.g. incompatible CubeMX versions, missing software packages and so on. If this is a case, please read and fix them, then try to re-run the generation action. Also, the output of the code generation feature in CubeMX is pretty different when running from the CLI or GUI mode of the CubeMX, so doesn't let this to confuse you. The CLI one is always a correct one if you plan to use the stm32pio, while the GUI one isn't compatible with the patching algorithm (see below). Also, the default structure of the generated code is significantly different when you invoke the generation from the GUI version of CubeMX or the CLI one. As stm32pio uses the latter, currently the PlatformIO project structure cannot be properly patched to use a code from the GUI version of CubeMX (at least with the default patch, you can always tweak it in a configuration file `stm32pio.ini`). +#### Prerequisites +`.ioc` file with the compatible parameters: + - "Copy only the necessary library files" should be set to `True` (`ProjectManager.LibraryCopy=1` in the `.ioc` file) + - "Generate periphery initialization as a pair of '.c/.h' files per peripheral" should be set to `True` (`ProjectManager.CoupleFile=true` in the `.ioc` file) + - "Other Toolchains (GPDSC)" for the toolchain (`ProjectManager.TargetToolchain=Other Toolchains (GPDSC)` in the `.ioc` file) + +Look at the [example](/examples/cli) to see how they can be set. +#### Expected output +✅ `Inc/` +✅ `Src/` + +### `pio_init` +Starts the PlatformIO to create the new project passing the compatible parameters (e.g. framework to use during the compilation). Running this command is basically the same as running the `platformio project init ...` manually. Typically, you shouldn't be in the situation when you need to execute this command by yourself, instead `new` or `generate` will be more practical most of the time. +#### Prerequisites +PlatformIO board identifier supplied (whether set in the config or passed as a CLI argument). +#### Expected output +✅ `lib/` +✅ `include/` +✅ `src/` +✅ `test/` +✅ `platformio.ini` +✅ `.gitignore` + +### `patch` +This is a "glue" actually coupling the CubeMX output and the expected by PlatformIO project structure. Note: this operation erases all the comments (lines starting with `;`) inside the `platformio.ini` file. They are not required anyway, in general, but if you need them for some reasons please consider saving the information somewhere else. +#### Prerequisites + - generated CubeMX code + - initialized PlatformIO project +#### Expected output +❌ `src/` +❌ `include/` +✏️ `platformio.ini` + +### `new` +Fulfill the complete run for the project passing it through all of the stages above. Additionally, optional build via PlatformIO can be initiated with the corresponding CLI key (basically `pio run` command). +#### Prerequisites +`.ioc` file. +#### Expected output +All of the above (+ optional build artifacts, if the corresponding option was given). + +There is no dedicated "build" command because this task can be done through the `--with-build` option (see below) or completely by PlatformIO itself (`pio run`). + + +## Utils + +### `clean` +Can be used to return the project to its original state while experimenting or to quickly remove some temporary files. By default, this will retain only the `.ioc` file, but you can specify the ignore-list (in the config) – files/folders to preserve. Alternatively, this task can be entirely entrusted to the git and its own rules. For example, a role of the ignore-list in this case can be played by the `.gitignore` list. Note: by default, you will be prompted about files/folders for removal. There is an option to suppress it but in this case you are on your own. +#### Prerequisites +`.ioc` file. +#### Expected output +Depends on configuration. + +### `status` +Inspect the project state and show the obtained information. All possible project stages will be printed while the fulfilled ones will be marked. +#### Prerequisites +None +#### Expected output +Terminal output. + +### `validate` +Inspect the current environment – tools listed under the "app" section of the config (i.e. CubeMX, PlatformIO). Allows to quickly check whether all these programs are correctly set and/or installed in your system. +#### Prerequisites +Config file. In case it doesn't exist, the default config will be tested although this, probably, is not very useful. +#### Expected output +Terminal output. + +### `gui` +Start the GUI version of the application. All arguments given will be passed forward. See [its own docs](/docs/GUI) for more information. +#### Prerequisites +GUI dependencies installed (PySide2). +#### Expected output +None (GUI window appears). + + +## Options +Although every main command listed above has its own set of available options, some of them are common across multiple ones. Remember you can always run `-h/--help` option to see topical info. + +### `-d/--directory PATH` +Pass the project folder. Alternatively, the `.ioc` file itself can be specified. Despite this being the fundamental identifier, you can omit it entirely in your commands calls. In this case the current working directory will be assumed as the project's one. Basically like for git, PlatformIO and many other CLI tools. +#### Default +Current working directory. + +### `-b/--board` +PlatformIO identifier of the board. In other words, pick the "ID" column of the `platformio boards` command output. +#### Default +None. + +### `-e/--start-editor` +Many of the code/text editors (both CLI and GUI ones) can be started from the terminal, e.g. VSCode – by the `code` command, Sublime – `subl` and so on. The second CLI argument is often the desired folder path to open so using the formula `[EDITOR] [PATH]` we can satisfy most of the conforming editors. Furthermore, it can actually be used as a generic post-action hook as long the arguments' formula is suitable. +#### Default +None. + +### `-c/--with-build` +Build the project in the end. See `new` command description. +#### Default +False. + +### `clean` options +`-s/--store-content` – get the current content of the project folder, save it to the `cleanup_ignore` config option and exit. + +**Default**: False. + +`-q/--quiet` – suppress the prompt about the files/folders to delete. Be careful, it is recommended to use this option only after the first successful removal. + +**Default**: True. diff --git a/docs/CONFIG.md b/docs/CONFIG.md new file mode 100644 index 0000000..96c86dc --- /dev/null +++ b/docs/CONFIG.md @@ -0,0 +1,99 @@ +# INI-config description +Consider this file as a reference when editing the project parameters. + +The project's configuration file (by default, its name is `stm32pio.ini`) controls aspects of how the stm32pio treating your project. INI-format is convenient and familiar to PlatformIO users. + +It has 2 main sections. As the stm32pio has no global config (keeping be simple and non-intrusive), the `[app]` section consists of some properties that could belong to the global app settings rather being set per-project. We're talking here about the CLI tools' (used by the stm32pio) paths/commands. The second section – `[project]` – is more related to the particular project. + +By default, all available settings are explicitly placed inside an every INI config. It is recommended to not remove them from the file. + +Some config properties can also be supplied by the CLI keys. So what is the resolution order in such case? +``` + defaults <= config file <= user-given + (settings.py module) stm32pio.ini CLI keys +``` +Right-hand values takes precedence over the left (arrows showing the merging order). + +Note: this is not an only source of the program settings but more like a "public" subset of them. As you can see above, there is also the `settings.py` module controlling internal parameters. + + +## Table of contents +> - [`app` section](#app-section) +> - [`java_cmd`](#java_cmd) +> - [`platformio_cmd`](#platformio_cmd) +> - [`cubemx_cmd`](#cubemx_cmd) +> - [`project` section](#project-section) +> - [`cubemx_script_content`](#cubemx_script_content) +> - [`platformio_ini_patch_content`](#platformio_ini_patch_content) +> - [`board`](#board) +> - [`ioc_file`](#ioc_file) +> - [`cleanup_ignore`](#cleanup_ignore) +> - [`cleanup_use_git`](#cleanup_use_git) +> - [`last_error`](#last_error) + + +## `app` section +Specify commands of the corresponding tools if they are present in your PATH env variable (e.g. `java`, `platformio`). Alternatively, provide an absolute path (e.g. `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX/STM32CubeMX.exe`). If the path contains whitespaces, do not escape them manually, this will be done automatically. + +### `java_cmd` +As you're probably already know, the CubeMX uses Java to run. So most likely it is already installed on your machine. By default, this command will be used to start the CubeMX as `java -jar` as it is the most universal and reliable approach. If omitted, there will be an attempt to run `cubemx_cmd` on its own, without preceding `java`. See `cubemx_cmd` below for more information. +#### Default +`java` + +### `platformio_cmd` +`python -m platformio` method is not currently supported. +#### Default +`platformio` + +### `cubemx_cmd` +As the CubeMX doesn't by default append itself to a PATH, this probably will be a path on your machine. +#### Default + - macOS: `/Applications/STMicroelectronics/STM32CubeMX.app/Contents/Resources/STM32CubeMX` + - Linux: `~/STM32CubeMX/STM32CubeMX` + - Windows: `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX/STM32CubeMX.exe` + + +## `project` section + +### `cubemx_script_content` +Template of the CubeMX script that will be filled, written to the temp file and fed to the CubeMX during the code generation process. In other words, they are instructions for the CubeMX to execute. +#### Default +``` +config load ${ioc_file_absolute_path} +generate code ${project_dir_absolute_path} +exit +``` + +### `platformio_ini_patch_content` +Changes that should be applied to the `platformio.ini` file to conform the CubeMX and PlatformIO projects structures. For those who want to modify the patch: it has a general .INI-style syntax, so it is possible to specify several sections and apply composite patches. This works totally fine for the most cases except, perhaps, some really huge complex patches involving, say, the parameters' interpolation feature. It's turned off for both `platformio.ini` and user's patch parsing by default. If there are some problems you've encountered due to a such thing please modify the source code to match the parameters' interpolation behavior for the configs you need to. Seems like `platformio.ini` uses `ExtendedInterpolation` for its needs, by the way. +#### Default +``` +[platformio] +include_dir = Inc +src_dir = Src +``` + +### `board` +Same as the corresponding CLI option – PlatformIO name (ID) of the board. +#### Default +None. + +### `ioc_file` +`.ioc` file to work with (placed in the project root). This is not particularly useful when there is only a single one, but can be valuable when there are multiple. +#### Default +Name of the first `.ioc` file found, or an explicitly specified one. + +### `cleanup_ignore` +List of paths relative to the project root that should be ignored (left) during the cleaning operation. Alternatively, each line specified can be a glob-style pattern. The list will be ignored if `cleanup_use_git` is set to True. +#### Default +Value of the `ioc_file`. + +### `cleanup_use_git` +Boolean controlling the `clean` method: whether to utilize custom ignore list and remove the rest of the files or to delegate the task to git (`git clean`). +#### Default +`False` + +### `last_error` +This isn't really a "parameter" and initially doesn't exist at all but appears in your config after some error occurs. This will contain an error string and its Python traceback so you can examine it later to solve the problem. This will be automatically cleared after the next successful operation on this project. +#### Default +None. diff --git a/docs/GUI/README.md b/docs/GUI/README.md new file mode 100644 index 0000000..f073690 --- /dev/null +++ b/docs/GUI/README.md @@ -0,0 +1,74 @@ +# stm32pio GUI + +![Main](main_window.png) + +The cross-platform GUI version of the stm32pio. It wraps the core library functionality into the Qt5-QML skin using the PySide2 (aka "Qt for Python") and adds a projects' management feature allowing you to store and manipulate on multiple stm32pio projects at one place. + + +## Table of contents +> - [Install and run](#install-and-run) +> - [Usage](#usage) +> - [Architecture notes](#architecture-notes) + + +## Install and run +The app requires PySide2 of versions 5.14.2.3 or 5.15.2+ (early 5.15 versions has a bug making the Add/Remove buttons not active (https://bugreports.qt.io/browse/QTBUG-85130)) package. It should be available in all major package managers including pip, apt, brew and so on. + +The convenient way to install is via `pip` specifying `extras` option: +```shell script +$ pip install stm32pio[GUI] +``` + +If you have installed the basic CLI version, the GUI package is already on your machine, so you can reinstall it using the command above or just supplement the existing setup installing the PySide2 manually. + +Then it can be started from anywhere as +```shell script +$ stm32pio gui # or +$ stm32pio_gui +``` + +If you rather want to launch completely from sources, it is possible like this: +```shell script +$ python path/to/stm32pio/gui/app.py +``` +or +```shell script +stm32pio-repo/ $ python -m stm32pio.gui +``` + +Either way, you can additionally specify the project (and board ID) to start with: +```shell script +$ stm32pio gui -d ./sample-project -b discovery_f4 +``` + + +## Usage +Add a folder with an `.ioc` file to begin with - it will be your first project. You can either use the "Add" button or drag-and-drop it into the main window, in latter case you also have an ability to add multiple projects simultaneously. If a project is empty, the initialization screen will be shown to help in a configuration: + +![Init](usage_tutorial_screenshots/init_screen.png) + +Skip it or enter one of the available PlatformIO STM32 boards identifier. Optionally select "Run" to apply all actions to the project (analog of the `new` CLI command). + +At the main screen the buttons row allows you to run specific actions while, at the same time, is representing the current state of project. Green color means that this stage is fulfilled. The active project is monitored automatically while all the others refreshes only when you click on them, so the "stage" line at the projects list item can be outdated. + +Let's assume you've worked on some feature for some time (outside the stm32pio) and now need to re-generate and rebuild the configuration. To schedule all the necessary actions to run one after another, navigate to the last desired action while pressing the **Shift** key. All the actions prior this one should be colored light-green now: + +![Highlighting](usage_tutorial_screenshots/highlighting.png) + +**Shift**-click on it to execute the series. The picked actions will be framed inside a bold border around each of them: + +![Group](usage_tutorial_screenshots/group.png) + +Add **Ctrl** to the mouse click to start the editor specified in the settings after the action (it can be combined with a **Shift** as well). **Hint:** specify the `start` as "Editor" command to open the project folder in the new Explorer window (for Windows), or `open` for the Finder (on macOS). So it is, basically, a generic shell script which can be activated post operations +``` +