diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..392ff2d4f89 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,240 @@ +# Analog Devices MSDK Development and Contribution Guidelines + +## Development Flow + +Development for the MSDK also follows the official [GitHub development flow guidelines](https://docs.github.com/en/get-started/quickstart/github-flow). + +For beginners, [learngitbranching.js.org](https://learngitbranching.js.org/) is a great hands-on starting resource. + +## Contribution Guidelines + +The MSDK follows the [GitHub contribution guidelines](https://docs.github.com/en/get-started/quickstart/contributing-to-projects). + +External contributions from outside the [Analog Devices organization](https://github.com/Analog-Devices-MSDK) should be made via a Pull Request opened from a fork. Internal contributions should also preferrably use a fork where possible. + +If a direct branch on the mainline MSDK repo is made, the following branch naming conventions should be used when possible: + +* Bugfix/ticket: `fix/branchname` + * For Jira tickets, it's recommended to use `fix/ticketnumber` so that the branch gets automatically tracked. Ex: `fix/MSDK-670` +* New feature: `feature/branchname` +* Generic development branch: `dev/branchname` +* New and/or modified example branch: `example/branchname` + +## Style Guide + +The MSDK code-base, for the most-part, follows the [Linux Kernel coding style](https://www.kernel.org/doc/html/v4.10/process/coding-style.html#linux-kernel-coding-style) _and_ [Google's C++ Style Guide](https://google.github.io/styleguide/cppguide.html) with the following exception(s): + +* Indentations are 4 spaces. + +Formatting and styling is enforced via [clang-format](https://www.kernel.org/doc/html/latest/process/clang-format.html) and [cpplint](https://github.com/cpplint/cpplint), which automatically run checks against all PRs. A PR cannot be merged until it passes these checks. + +### Running the Linter & Formatter + +Both utilities can be run locally. cpplint should be run first, then clang-format. Additionally, both should be run from the root directory of the MSDK repo so that their config files are loaded properly. + +clang-format rules are loaded from [.clang-format](.clang-format) and cpplint rules are loaded from [CPPLINT.cfg](CPPLINT.cfg). + +#### cpplint + +[cpplint](https://github.com/cpplint/cpplint) enforces good code practices by scanning for common mistakes and ensuring certain higher-level code patterns are followed. It's a good idea to resolve the errors found by cpplint before before running clang-format, which deals with lower-level code styling and syntax patterns. + +1. `cd` into the root directory of the MSDK repo. + +2. Run cpplint. + + To run cpplint on a **file**, use `cpplint `. + + ```shell + $ cpplint Examples/MAX78000/Hello_World/main.c + Done processing Examples/MAX78000/Hello_World/main.c + ``` + + To recursively run cpplint on an **entire directory**, use `cpplint --recursive `. + + ```shell + $ cpplint --recursive Examples/MAX78000 + + Examples/MAX78000/ADC/example_config.h:1: #ifndef header guard has wrong style, please use: EXAMPLES_MAX78000_ADC_EXAMPLE_CONFIG_H_ [build/header_guard] [5] + Examples/MAX78000/ADC/example_config.h:14: #endif line should be "#endif // EXAMPLES_MAX78000_ADC_EXAMPLE_CONFIG_H_" [build/header_guard] [5] + Done processing Examples/MAX78000/ADC/example_config.h + Done processing Examples/MAX78000/ADC/main.c + Done processing Examples/MAX78000/AES/main.c + Done processing Examples/MAX78000/ARM-DSP/arm_bayes_example/arm_bayes_example_f32.c + ... + ``` + +3. Resolve any errors. + +4. `git add` and `git commit` any changes to your code. + +#### clang-format + +[clang-format](https://www.kernel.org/doc/html/latest/process/clang-format.html) is a code formatter and style checker that enforces a common style for the code-base. + +1. `cd` into the root directory of the MSDK repo. + +2. Run clang-format. + + The `--style=file --Werror --verbose` options are shared across all runs. + + To run a clang-format _check_ on a file, use the `-n` "dry-run" flag. + + `clang-format --style=file --Werror --verbose -n ` + + For example: + + ```shell + $ clang-format --style=file --Werror --verbose -n Examples/MAX78000/CRC/main.c + + Formatting [1/1] Examples/MAX78000/CRC/main.c + Examples/MAX78000/CRC/main.c:86:40: error: code should be clang-formatted [-Wclang-format-violations] + for (i = 0; i < DATA_LENGTH; i++) { array[i] = i; } + ^ + ``` + + To _apply_ the formatter to automatically format a file, use the `-i` flag. + + `clang-format --style=file --Werror --verbose -i ` + + For example: + + ```shell + clang-format --style=file --verbose -i Examples/MAX78000/CRC/main.c + Formatting [1/1] Examples/MAX78000/CRC/main.c + ``` + + This will apply the formatter and overwrite the file. Check the formatter's work using `git diff`. + + ```diff + diff --git a/Examples/MAX78000/CRC/main.c b/Examples/MAX78000/CRC/main.c + index 1dda1feed..c16ceb962 100644 + --- a/Examples/MAX78000/CRC/main.c + +++ b/Examples/MAX78000/CRC/main.c + @@ -83,7 +83,9 @@ void Test_CRC(int asynchronous) + + printf(asynchronous ? "TEST CRC ASYNC\n" : "TEST CRC SYNC\n"); + + - for (i = 0; i < DATA_LENGTH; i++) { array[i] = i; } + + for (i = 0; i < DATA_LENGTH; i++) { + + array[i] = i; + + } + ``` + + To apply the formatter to multiple files, the `*` and `**` wildcard characters can be used. `*` matches any file or folder, and `**` _recursively_ matches any file or folder. + + To recursively run clang-format on all C files in an entire directory, use: + + `clang-format --style=file --verbose -n /**/*.c`. + + For example: + + ```shell + $ clang-format --style=file --verbose -i Examples/MAX78000/ARM-DSP/**/*.c + + Formatting [1/24] Examples/MAX78000/ARM-DSP/arm_bayes_example/arm_bayes_example_f32.c + Formatting [2/24] Examples/MAX78000/ARM-DSP/arm_class_marks_example/arm_class_marks_example_f32.c + Formatting [3/24] Examples/MAX78000/ARM-DSP/arm_convolution_example/arm_convolution_example_f32.c + Formatting [4/24] Examples/MAX78000/ARM-DSP/arm_convolution_example/math_helper.c + Formatting [5/24] Examples/MAX78000/ARM-DSP/arm_dotproduct_example_f32/arm_dotproduct_example_f32.c + ... + ``` + + ... which runs the formatter for all C files in the `Examples/MAX78000/ARM-DSP` directory _and all its subdirectories_. + +4. `git add` and `git commit` any changes to your code. Now, it's ready for a PR! The same checks will be automatically run against any PRs that are opened in the MSDK, and they must pass before the code can be approved. + +## Examples + +### Updating and Adding Examples + +1. First, ensure that the example project has been linted and formatted to follow the [Style Guide](#style-guide) + +2. Copy the example project into the [Examples](https://github.com/Analog-Devices-MSDK/msdk/tree/main/Examples) folder of the SDK for the applicable target microcontrollers. + +3. `git add` and `git commit` the Example project. Use a commit message such as "Add xxx Example" + +4. Run the [MSDKGen](https://github.com/Analog-Devices-MSDK/MSDKGen) utility to ensure the example project's support files are updated to the latest version. + + If you are coming from the **_legacy_ Makefile system** (no project.mk) it's best to migrate the old Makefile in its own commit... + + 1. Generate the new Makefile first using the `--no-vscode`, `--no-eclipse`, and `--backup` options. Ex: + + ```shell + python msdkgen.py update-all --projects yourprojectname --no-vscode --no-eclipse --overwrite --backup + ``` + + 2. A project.mk file will be added, and the old Makefile will be replaced but _backed up_ to a file called `Makefile-backup.mk`. + + 3. Migrate any project-specific build settings to project.mk. Documentation on the project.mk system can be found [here](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop). + + 4. `git add` and `git commit` the new Makefile and project.mk files. Delete the backup file. + + 5. Run a full `update-all`, which will then update the VSCode and Eclipse files as well. + + Otherwise, if the project is already running a [project.mk](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration) file then a full `update-all` command can be used. + + Ex: + + ```shell + python msdkgen.py update-all --projects yourprojectname --overwrite + ``` + +5. If the updated files break any projects they can be restored to the previously working version using the `git restore` command. + + For example, the command below will restore all files in your current working directory. + + ```shell + git restore ** + ``` + + The `git diff` command can also be used to inspect local changes to help identify the root cause. Ex: + + ```shell + git diff ./ + ``` + + If MSDKGen breaks a previously working project _that has already been migrated to the project.mk build system_ please report it to the [MSDKGen Issue Tracker](https://github.com/Analog-Devices-MSDK/MSDKGen/issues) + +## Libraries + +Libraries should be added to the [Libraries](Libraries) sub-folder of the MSDK. + +* All libraries should include a `libraryname.mk` file that can be added to [libs.mk](Libraries/libs.mk) via a toggle-switch. The filename should match the name of library as closely as possible, and expose any required [configuration variables](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration). + +* If necessary, a library may also include a "core" Makefile or set of Makefiles to build it as a standalone static library file. The naming convention is `lib.a`. + +### Self-Locating Makefile + +The first thing that the `libraryname.mk` file should do is locate its own directory and store it in a variable. The code snippet can be used to achieve this. + +```Makefile +ifeq "$(LIBRARYNAME_DIR)" "" +# If LIBRARYNAME_DIR is not specified, this Makefile will locate itself. +LIBRARYNAME_DIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST)))) +endif +``` + +All filepaths for the library should then use this `$(LIBRARYNAME_DIR)`-type variable as their "root" for all filepaths. This is a safe and reliable way to self-reference internal library files. + +For an example, see the [periphdriver.mk](Libraries/PeriphDrivers/periphdriver.mk) file. + +### Simple Libraries + +For simple libraries, it may be sufficient to just add the library's source files to the build using `VPATH` and `IPATH`. + +For example: + +```Makefile +IPATH += $(LIBRARY_NAME_DIR)/include +VPATH += $(LIBRARY_NAME_DIR)/src +SRCS += libfile1.c +SRCS += libfile2.c +``` + +An example of this is [MiscDrivers](Libraries/MiscDrivers/), which is a simple source-file-only library. It gets its source code selectively added to the build via [board.mk](Libraries/Boards/MAX78000/EvKit_V1/board.mk) files. + +### Advanced Libraries + +More advanced libraries (including those with a large number of source files) should include a rule to build as a static library file with a [recursive Make call](https://www.gnu.org/software/make/manual/make.html#Recursion). + +This type of library should also set up the appropriate [configuration variables](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration) to include that static library to the build. diff --git a/README.md b/README.md index f68a9909d7f..9a6ac58c2e5 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ -License Agreement -===================== +# Analog Devices MSDK + +## License Agreement **© Copyright (C) 2022 Maxim Integrated Products, Inc., All rights Reserved.** @@ -23,13 +24,13 @@ 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.** -Except as contained in this notice, the name of **Maxim Integrated Products, Inc.** +Except as contained in this notice, the name of **Maxim Integrated Products, Inc.** shall not be used except as stated in the **Maxim Integrated Products, Inc. Branding Policy.** The mere transfer of this software does not imply any licenses of trade secrets, proprietary technology, copyrights, patents, trademarks, maskwork rights, or any other form of intellectual -property whatsoever. **Maxim Integrated Products, Inc.** retains all +property whatsoever. **Maxim Integrated Products, Inc.** retains all ownership rights. [Final Copyright](https://www.maximintegrated.com/en/aboutus/legal/copyrights/default-copyright.html "Final Copyright") @@ -38,36 +39,41 @@ ownership rights. ## Introduction -The Maxim Microcontrollers SDK (MaximSDK), now a part of Analog Devices, contains tools and resources to develop firmware for the [MAX-series of microcontrollers](https://www.maximintegrated.com/en/products/microcontrollers.html). This includes register files, peripheral drivers, system startup files, documentation, various utilities, third-party libraries, IDE support files, and a toolchain. +The Maxim Microcontrollers SDK (MSDK), now a part of Analog Devices, contains tools and resources to develop firmware for the [MAX-series of microcontrollers](https://www.maximintegrated.com/en/products/microcontrollers.html). This includes register files, peripheral drivers, system startup files, documentation, various utilities, third-party libraries, IDE support files, and a toolchain. + +The following development environments are supported: -This repository contains the latest source code of the MaximSDK and is used for development. It does _not_ contain the MaximSDK _toolchain_, which is a separate collection of programs used to build, program, and debug the contents of this repo on hardware. +* Command-line development +* Eclipse +* Visual Studio Code +* IAR +* Keil -Currently, the MaximSDK toolchain is currently built around [GNU Make](https://www.gnu.org/software/make/), a [custom fork](https://github.com/Analog-Devices-MSDK/openocd) of [OpenOCD](https://openocd.org/), and [GNU GCC](https://www.bing.com/ck/a?!&&p=e191484d4651f3b3JmltdHM9MTY1ODUyNzg2NiZpZ3VpZD04ODEwYTM3NS1iM2FlLTQ3MGQtYTVjYS0zMjNmMmZlNWVkZWEmaW5zaWQ9NTE4Mg&ptn=3&hsh=3&fclid=2e9aac62-0a0b-11ed-99a6-78b7c6a38599&u=a1aHR0cHM6Ly9nY2MuZ251Lm9yZy8&ntb=1) ([Arm GNU Toolchain](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain#:~:text=The%20GNU%20Arm%20Embedded%20toolchain%20contains%20integrated%20and,on%2032-bit%20Arm%20Cortex-A%2C%20Cortex-R%20and%20Cortex-M%20processors.) for Cortex-M development and [xPack RISCV GCC](https://github.com/xpack-dev-tools/riscv-none-embed-gcc-xpack) for RISC-V development) +This repository contains the latest source code of the MSDK and is used for development. It does _not_ contain the MSDK _toolchain_, which is a separate collection of programs used to build, program, and debug the contents of this repo on hardware. -The full MaximSDK (including its toolchain) is available via an [Automatic Installer](#automatic-installer), which pulls from the latest release tag and packages it alongside the toolchain. +The full MSDK is available via an [Automatic Installer](#automatic-installer), which pulls from the latest release tag of this repo and packages it alongside the toolchain. -Users who would like to retrieve the bleeding-edge development copies of the MaximSDK resources can also pull them from this repo. See [Installing from the Github Repo](#installing-from-the-github-repo) +Users who would like to retrieve the bleeding-edge development copies of the MSDK resources can pull them from this repository. See [Developing from the Repo](#developing-from-the-repo). ## Installation ### Automatic Installer -The MaximSDK is available via an automatic installer for the platforms below. The automatic installer will retrieve the latest _release_ version of this repository _and_ the latest toolchain for your OS. +The MSDK is available via an automatic installer for the platforms below. The automatic installer will retrieve the latest _release_ version of this repository and the latest toolchain for your OS. * [Windows 10](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0010820A) * [Ubuntu Linux](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0018720A) - * This file must be made executable before it can be run. Use the command `chmod +x MaximMicrosSDK_linux.run`. Alternatively, set “Allow executing as program” in the Ubuntu GUI. + * This file must be made executable before it can be run. Use the command `chmod +x MaximMicrosSDK_linux.run`. Alternatively, set “Allow executing as program” in the Ubuntu GUI. * [MacOS](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0018610A) - * Some additional steps are required to complete the automatic installation on MacOS. See the [Completing the Installation on MacOS](#completing-the-installation-on-macos) below. - + * Some additional steps are required to complete the automatic installation on MacOS. See the [Completing the Installation on MacOS](#completing-the-installation-on-macos) below. ### Cloning the Github Repo -This repo can be cloned to obtain the latest development copies of the MaximSDK source code. +This repo can be cloned to obtain the latest development copies of the MSDK source code. 1. First, you'll need to set up an SSH key for your Github account. See the [Github Docs on SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) for instructions. @@ -77,12 +83,11 @@ This repo can be cloned to obtain the latest development copies of the MaximSDK git clone --recurse git@github.com:Analog-Devices-MSDK/msdk.git ``` -The source code in the repo can now be copied elsewhere, but if you'd like to set up the repo for "in-place" development you'll also need to perform a few manual steps to link the toolchain. See [Developing from the Repo](#developing-from-the-repo) - +The source code in the repo can now be copied elsewhere, but if you'd like to set it up for "in-place" development you'll also need to perform a few manual steps to link the toolchain. See [Developing from the Repo](#developing-from-the-repo). ### Developing from the Repo -The Github repo does not contain a copy of the toolchain. In order to develop directly on the repo the toolchain must be linked into it. +The Github repo contains source code only. In order to develop on it directly the toolchain must be made available at the same file-paths as the full MSDK installation. The easiest way to do this is to retrieve the toolchain with the automatic installer and then create symbolic links. This section walks through the process. 1. Install the toolchain via the [Automatic Installer](#automatic-installer) for your OS if you haven't already. @@ -92,37 +97,92 @@ The Github repo does not contain a copy of the toolchain. In order to develop d * Open On-Chip Debugger * MSYS2 (if you're on Windows 10) - If you've already installed the MaximSDK, run the `MaintenanceTool` program to ensure these components are selected and updated to the latest version. + If you've already installed the MSDK, run the `MaintenanceTool` program to ensure these components are selected and updated to the latest version. -2. Create symbolic directory links to link the toolchain at the expected locations. +2. Clone the Github repository to an accessible location without any spaces in its filepath. See [Cloning the Github Repo](#cloning-the-github-repo). - On **Windows**, open a terminal as administrator and `cd` into the cloned repo. Then, use the `mklink` command. - - Ex (with the MaximSDK installed to the default location): +3. Create symbolic directory links to link the toolchain at the expected locations. - ```shell - mklink /D Tools\GNUTools C:\MaximSDK\Tools\GNUTools && mklink /D Tools\OpenOCD C:\MaximSDK\Tools\OpenOCD && mklink /D Tools\MSYS2 C:\MaximSDK\Tools\MSYS2 && mklink /D Tools\xPack C:\MaximSDK\Tools\xPack - ``` + On **Windows**: + * Open a **command prompt** _as administrator_. - On **Linux/MacOS**, open a terminal and `cd` into the cloned repo. Then, use the `ln` command. + * `cd` into the cloned location of the Github repo from step 2. - Ex (with the MaximSDK installed to the default location): + * Run the following commands. If you installed the MSDK to a non-default location in step 1, change `C:\MaximSDK` to point to the location you chose. - ```shell - ln -s ~/MaximSDK/Tools/GNUTools Tools/GNUTools && ln -s ~/MaximSDK/Tools/OpenOCD Tools/OpenOCD && ln -s ~/MaximSDK/Tools/xPack Tools/xPack - ``` + ```cmd + mklink /D Tools\GNUTools C:\MaximSDK\Tools\GNUTools + ``` + + ```cmd + mklink /D Tools\OpenOCD C:\MaximSDK\Tools\OpenOCD + ``` + + ```cmd + mklink /D Tools\MSYS2 C:\MaximSDK\Tools\MSYS2 + ``` + + ```cmd + mklink /D Tools\xPack C:\MaximSDK\Tools\xPack + ``` + + Example output: + + ```cmd + C:\Users\Username\repos\msdk>mklink /D Tools\GNUTools C:\MaximSDK\Tools\GNUTools + symbolic link created for Tools\GNUTools <<===>> C:\MaximSDK\Tools\GNUTools - The Github repo now has a virtual copy of the toolchain at the expected locations. + C:\Users\Username\repos\msdk>mklink /D Tools\OpenOCD C:\MaximSDK\Tools\OpenOCD + symbolic link created for Tools\OpenOCD <<===>> C:\MaximSDK\Tools\OpenOCD -3. For **command-line** development add the following paths system's Path, replacing `repo` with the actual cloned location of the repository. + C:\Users\Username\repos\msdk>mklink /D Tools\MSYS2 C:\MaximSDK\Tools\MSYS2 + symbolic link created for Tools\MSYS2 <<===>> C:\MaximSDK\Tools\MSYS2 - * `repo/Tools/GNUTools/10.3/bin` - * `repo/Tools/OpenOCD` - * `repo/Tools/xPack/riscv-none-embed-gcc/10.2.0-1.2/bin` - * `repo/Tools/MSYS2/usr/bin` (On Windows only) + C:\Users\Username\repos\msdk>mklink /D Tools\xPack C:\MaximSDK\Tools\xPack + symbolic link created for Tools\xPack <<===>> C:\MaximSDK\Tools\xPack -4. For development with **[Visual Studio Code](https://github.com/Analog-Devices-MSDK/VSCode-Maxim)**, simply set `MAXIM_PATH` in your global settings.json file to the location of the Github repo. See step 10 of the [VSCode-Maxim installation](https://github.com/Analog-Devices-MSDK/VSCode-Maxim#installation) instructions for more details. VS Code will now load source code from the Github repo and the example projects should behave as expected. + ``` + On **Linux/MacOS**: + * Open a terminal + + * `cd` into the cloned location of the Github repo from step 2. + + * Run the following commands. If you installed the MSDK to a non-default location in step 1, change `~\MaximSDK` to point to the location you chose. + + ```shell + ln -s ~/MaximSDK/Tools/GNUTools Tools/GNUTools + ``` + + ```cmd + ln -s ~/MaximSDK/Tools/OpenOCD Tools/OpenOCD + ``` + + ```cmd + ln -s ~/MaximSDK/Tools/xPack Tools/xPack + ``` + + You can use `ls -la Tools` to verify the links have been created successfully. + + Example output: + + ```shell + username@machine:~/repos/msdk$ ln -s ~/MaximSDK/Tools/GNUTools Tools/GNUTools + username@machine:~/repos/msdk$ ln -s ~/MaximSDK/Tools/OpenOCD Tools/OpenOCD + username@machine:~/repos/msdk$ ln -s ~/MaximSDK/Tools/xPack Tools/xPack + username@machine:~/repos/msdk$ ls -la Tools + total 20 + drwxr-xr-x 5 username username 4096 Oct 4 16:32 . + drwxr-xr-x 9 username username 4096 Oct 4 16:29 .. + drwxr-xr-x 2 username username 4096 Oct 4 16:29 BitmapConverter + drwxr-xr-x 2 username username 4096 Oct 4 16:29 Bluetooth + lrwxrwxrwx 1 username username 40 Oct 4 16:32 GNUTools -> /home/username/MaximSDK/Tools/GNUTools + lrwxrwxrwx 1 username username 39 Oct 4 16:32 OpenOCD -> /home/username/MaximSDK/Tools/OpenOCD + drwxr-xr-x 6 username username 4096 Oct 4 16:29 SBT + lrwxrwxrwx 1 username username 37 Oct 4 16:32 xPack -> /home/username/MaximSDK/Tools/xPack + ``` + +4. The MSDK now contains a virtual copy of the toolchain at the correct locations. Some additional setup may be required to use it depending on your chosen development environment. See [Setup](#setup) below. ### Completing the Installation on MacOS @@ -138,7 +198,6 @@ On MacOS, some additional missing packages must be manually installed via [Homeb brew install libusb-compat libftdi hidapi libusb ``` - **For M1 platforms**: You must use a Rosetta terminal to install Homebrew: @@ -168,3 +227,198 @@ You must use a Rosetta terminal to install Homebrew: ```shell brew install libusb-compat libftdi hidapi libusb ``` + +## Setup + +The setup guides below demonstrate how to configure supported development environments for use with this repository. It assumes a successful [installation](#installation). + +### Visual Studio Code + +All example projects in the MSDK come pre-configured with [Visual Studio Code](https://code.visualstudio.com/) project folders that are managed by the [VSCode-Maxim](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop) repository. They can be found in the `.vscode` sub-folder of each example, and include local copies of the VSCode-Maxim documentation. + +The setup procedure is exactly the same as a standard VSCode-Maxim installation (instructions [here](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#installation)), except on step 9 `"MAXIM_PATH"` can be set to the location of this repository instead of the release version of the MSDK. + +See [Usage](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#usage) from the VSCode-Maxim readme for more details on using the projects once setup is complete. + +### Eclipse + +Eclipse itself should be launched with the `Tools/Eclipse/cdt/eclipse(.bat/.sh)` script, which will set `MAXIM_PATH` and a few other environment variables for use with the _release_ version of the MSDK by default. Therefore, there are two options for using Eclipse with the MSDK development repository: + +#### Option 1 - Project Settings + +1. Import or open a project in your Eclipse workspace. + +2. Right click on the project and select `Properties`. + +3. Navigate to `C/C++ Build -> Environment`. + +4. Add a _new_ environment variable. Set: + + * Name: `MAXIM_PATH` + + * Value: Installed location of this repository. Ex: `C:\Users\JCarter3\repos\msdk`. + + * Select **"Add to all configurations"** + +5. Ensure the **"Replace native environment with the specified one"** option is selected. + +6. Hit "Apply" -> "Apply and Close". + +7. Clean the project. + +The project is now configured for use with the MSDK development repo, and subsequent builds will load the latest development resources. + +#### Option 2 - Edit setenv + +1. Locate the `setenv.bat` script that can be found in the root directory of the _release_ MSDK installation. + +2. (Optional, recommended) Copy the `setenv.bat` file to a backup called `setenv-release.bat`. This backup file can be used to revert back to the original if needed. + +3. Open the `setenv.bat` script in a text editor. + +4. Change the line + + ```bat + set MAXIM_PATH=%CD% + ``` + + to set `MAXIM_PATH` to the installed location of this repository. For example: + + ```bat + set MAXIM_PATH=C:\Users\Username\repos\msdk + ``` + +**Note:** This will configure _all_ Eclipse sessions to load resources from the development repo. + +### Command-line Setup + +This section assumes some familiarity with basic terminal concepts such as your system's Path and environment variables. Since there are such wide variety of terminal applications and Operating Systems, these instructions are intentionally left somewhat generic. + +However, an example `.bashrc` file is provided below that can be referenced for most Unix systems. Simply copy and paste the entries below into your shell's startup script and edit `MAXIM_PATH` to the installed location of this repository. + +```bash +# ~/.bashrc + +# Set MAXIM_PATH environment variable +export MAXIM_PATH=#changeme! + +# Add Arm Embedded GCC to path (v10.3) +export ARM_GCC_ROOT=$MAXIM_PATH/Tools/GNUTools/10.3 +export PATH=$ARM_GCC_ROOT/bin:$PATH + +# Add xPack RISC-V GCC to path (v10.2) +export XPACK_GCC_ROOT=$MAXIM_PATH/Tools/xPack/riscv-none-embed-gcc/10.2.0-1.2 +export PATH=$XPACK_GCC_ROOT/bin:$PATH + +# Add OpenOCD to path +export OPENOCD_ROOT=$MAXIM_PATH/Tools/OpenOCD +export PATH=$OPENOCD_ROOT:$PATH +``` + +More generic instructions can be found below. These instructions will use Unix syntax unless a step is targeted specifically at Windows. + +1. Create a new environment variable on your system called `MAXIM_PATH`. Set its value to the installed location of this repository. + +2. Add the following entries to your system's path: + + * `$MAXIM_PATH/Tools/GNUTools/10.3/bin` + * `$MAXIM_PATH/Tools/xPack/riscv-none-embed-gcc/10.2.0-1.2/bin` + * `$MAXIM_PATH/Tools/OpenOCD` + +3. (Windows only) Add the following entry to your system's path: + * `%MAXIM_PATH%/Tools/MSYS2/usr/bin` + +4. Restart your shell, and verify the tools are accessible with the following commands: + + 1. Arm Embedded GCC: + + ```shell + $ arm-none-eabi-gcc -v + + Using built-in specs. + COLLECT_GCC=arm-none-eabi-gcc + + # ... Lots of other info will be printed here... + + Supported LTO compression algorithms: zlib + gcc version 10.3.1 20210824 (release) (GNU Arm Embedded Toolchain 10.3-2021.10) + ``` + + 2. xPack RISC-V GCC: + + ```shell + $ riscv-none-embed-gcc -v + + Using built-in specs. + COLLECT_GCC=riscv-none-embed-gcc + + # ... Lots of other info will be printed here... + + Supported LTO compression algorithms: zlib + gcc version 10.2.0 (xPack GNU RISC-V Embedded GCC x86_64) + ``` + + 3. OpenOCD + + ```shell + $ openocd -v + + Open On-Chip Debugger 0.11.0+dev-g56a818e4c (2022-07-19-19:00) + Licensed under GNU GPL v2 + For bug reports, read + http://openocd.org/doc/doxygen/bugs.html + ``` + + **Note:** The automatic installer should have installed OpenOCD dependencies. Should any missing package errors get thrown on this command they can be resolved by installing the missing packages manually. + + **On linux:** + + ```shell + sudo apt-get install libusb-1.0 libusb-0.1 libhidapi-libusb0 libhidapi-hidraw0 + ``` + + **On MacOS with [Homebrew](https://brew.sh/)** + + ```shell + brew install libusb-compat libftdi hidapi libusb + ``` + + 4. GNU Make + + ```shell + $ make -v + + GNU Make 4.3 + Built for x86_64-pc-linux-gnu + Copyright (C) 1988-2020 Free Software Foundation, Inc. + License GPLv3+: GNU GPL version 3 or later + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. + ``` + + Make should also have been installed by the automatic installer. If Make is not available, install it with your package manager. + + **On linux:** + + ```shell + sudo apt-get install make + ``` + + **On MacOS with [Homebrew](https://brew.sh/)** + + ```shell + brew install make + ``` + +## Usage Quick-Start + +Following a successful [installation](#installation) and [setup](#setup), additional documentation on usage can be found below: + +* [Visual Studio Code](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#usage) +* [Eclipse](https://www.maximintegrated.com/en/design/technical-documents/userguides-and-manuals/6/6245.html) +* [IAR](https://www.youtube.com/playlist?list=PLQ4i891m2efIwwd4ScApoPv7RaYLwhAjF) +* [Keil](https://www.youtube.com/watch?v=d_O2tu5CMbQ) + +## Contributing + +Contributions to the MSDK are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.