diff --git a/Documentation/Development.md b/Documentation/Development.md index b9f94b2e..65e50955 100644 --- a/Documentation/Development.md +++ b/Documentation/Development.md @@ -1,30 +1,86 @@ # Development -Building this software can be performed two ways, using the STMCubeIDE or using command line tools. +Building this software can be performed two ways: using the STM32CubeIDE or using command line tools. -## STM Cube IDE +## STM32CubeIDE -The easiest way to start working using the STM Cube IDE is to create a new project for the STM32F103RCTx. -Then once this is created remove the auto-generated source code. -Next drag the contents of the `source` folder into the project and choose to link to files. -You will need to update the build settings for include paths & point to the new `.ld` linker file +The easiest way to start working with the STM32CubeIDE is to create a new project for the STM32F103RCTx. +Once this is created, remove the auto-generated source code. +Next, drag the contents of the `source` folder into the project and choose to link to files. +You will need to update the build settings for include paths and point to the new `.ld` linker file. -## Developing with command line tools & building a release +## Command line tools and building a release -In the `source` folder there is a makefile that can be used to build the repository using command line tools. -when running the `make` command, specify which model of the device & the language you would like to use. +In the `source` folder there is a `Makefile` that can be used to build the repository using command line tools. +When running the `make` command, specify which model of the device and the language(s) you would like to use. -`make -j8 lang=EN model=TS80` +### macOS -To build a release instead, run the build.sh script. This will update translations and also build every language for both TS100 and TS80 models. +Use the following steps to set up a build environment for IronOS on the command line (in Terminal). + +1. [Follow steps 1 – 3 here to install the toolchain](https://github.com/glegrain/STM32-with-macOS#0---installing-the-toolchain) needed to compile for STM32 microcontrollers. +2. Install `python`: +``` +brew install python +``` +3. (Optional) Update `pip` so it doesn't warn you about being out-of-date: +``` +python3 -m pip install --upgrade pip +``` +4. Change to the `source` directory: +``` +cd source +``` +5. Create a Python virtual environment for IronOS named `ironos-venv` to keep your Python installation clean: +``` +python3 -m venv ironos-venv +``` +6. Activate the Python virtual environment: +``` +source ironos-venv/bin/activate +``` +7. Install the dependencies required to run `make-translation.py`: +``` +pip install bdflib +``` +8. All done! See some examples below for how you can build your own IronOS. + +### Examples + +To build a single language Simplified Chinese firmware for the TS80P with 8 simultaneous jobs: +``` +make -j8 model=TS80P firmware-ZH_CN +``` + +To build a European multi-language firmware for the Pinecil with as many simultaneous jobs as there are logical processors on Linux: +``` +make -j$(nproc) model=Pinecil firmware-multi_European +``` + +To build a Cyrillic compressed multi-language firmware for the Pinecil with as many simultaneous jobs as there are logical processors on macOS: +``` +make -j$(sysctl -n hw.logicalcpu) model=Pinecil firmware-multi_compressed_Bulgarian+Russian+Serbian+Ukrainian +``` + +To build a custom multi-language firmware including English and Simplified Chinese for the TS80: +``` +make -j8 model=TS80 custom_multi_langs="EN ZH_CN" firmware-multi_Custom +``` + +To build a custom compressed multi-language firmware including German, Spanish, and French for the TS100 (note if `model` is unspecified, it will default to `TS100`): +``` +make -j8 custom_multi_langs="DE ES FR" firmware-multi_compressed_Custom +``` + +To build a release instead, run the `build.sh` script. This will update translations and also build every language for all device models. For macOS users, replace `make -j$(nproc)` in the script with `make -j$(sysctl -n hw.logicalcpu)` before running. ## Updating languages -To update the language translation files & associated font map, execute the `make_translation.py` code from the translations directory. +To update the language translation files and their associated font maps, execute the `make_translation.py` code from the `Translations` directory. ## Building Pinecil -I highly recommend using the command line tools and using docker to run the compiler. -It's a bit more fussy on setup than the STM tooling and this is by far the easiest way. -If you _need_ an IDE I have used [Nuclei's IDE](https://nucleisys.com/download.php) -And follow same idea as the STM Cube IDE notes above. +I highly recommend using the command line tools and using Docker to run the compiler. +It's a bit more fussy on setup than the STM tooling, and this is by far the easiest way. +If you _need_ an IDE I have used [Nuclei's IDE](https://nucleisys.com/download.php). +Follow the same idea as the STM Cube IDE notes above.