This article describes how to use Eclipse for project development with AmbiqSuite. All the material used in this article are based on Windows environment. The instructions described in this article shall also be applicable to other operating systems if the utility tools have a release version for the targeting operating system.
Setting up for Eclipse
Here's the list of tools/software needed for Eclipse.
- Java Runtime Environment (JRE)
- Needed by Eclipse to run. Check for the JRE version requirement from the section 'Running Eclipse' in readme_eclipse.html after Eclipse installation.
- Eclipse IDE for Embedded C/C++ Developers
- Using the latest release shall just be fine. For those who prefers to use the same release, the revision used in this article is 2020-09.
- Build Tools
- Windows version: https://github.com/xpack-dev-tools/windows-build-tools-xpack/
- Using the latest release shall just be fine. For those who prefers to use the same release, the revision used in this article is 4.3.0-1.
- GNU Toolchain
- or https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/
- Please check the GNU toolchain version which AmbiqSuite releases are tested with from the AmbiqSuite release note.
- SEGGER J-Link Software
- Please check the version requirement from the EVB quick start guide.
Development with Eclipse
Project & Source Files Import
AmbiqSuite provides preconfigured makefiles for every example projects and libraries. To import a project from AmbiqSuite into Eclipse:
- Navigate to 'File/Import'. In the popped out windows, select 'Existing Code as Makefile Project' in 'C/C++.' And then 'Next.'
- Pick the project to be imported. Make sure the import path is down to the folder 'gcc' of the project. Modify the project name properly and select 'Arm Cross GCC' as the toolchain for indexer setting.
Eclipse utilizes the existing Makefile for code compilation. This means, if a source/header file is to be added to or removed from the project, the Makefile needs to be updated accordingly. For source files, the exact file names need to be listed as well as the paths to the folders containing them. For header files, the paths to the folders where the header files are located need to be listed in the project Makefile.
After a project is imported into the workspace, only the files and the subfolders under the folder ‘gcc’ are listed. It is not mandatory to have source files included in a project in the workspace. But if one would like to use Eclipse not only for project compilation and debugging but also for development, follow the steps below to achieve so.
There are three types of folders in the workspace. The one ‘Linked Folder’ is used here. A linked folder is a link file pointing to an alternate location where the actual folder is located. Once a folder is added, Eclipse will list all files and subfolders underneath. For those who'd like to program in Eclipse, the following shows the steps to add the folder ‘src’ of the project ble_freertos_fit into the workspace.
- Right click on the project and navigate to 'New/Folder.'
- Click ‘Advanced,’ select ‘Linked to alternate location (Linked Folder)’ and complete the path in the field below. It’s a good practice to utilize the variables defined by Eclipse as much as possible. The resolved location shall display the correct path if the location is added correctly.
- Click ‘Finish.’ And now the folder ‘src’ and the files in it are added to the workspace now.
Follow the above steps to add the folders of interests one by one into the project in the workspace. The following screenshot shows several folders have been successfully added as linked folders. And these files are now accessible and can be navigated within Eclipse environment.
Please note again whether or not folders are added into the workspace, it does not affect the result of code compilation. The project still passes the build process but there would be symbol resolving errors which can be resolved by the steps in the section 'Symbol Resolution and Indexing' below.
Other than the toolchain setup described previously, two build variables need to be set up before the project can be compiled successfully.
Right click on the project and select 'Properties.' In 'C/C++ Build,' add by clicking 'Add...' on the right to 'Build Variables' the two variables cross_make and cross_prefix of the type 'String' with the the values make and arm-none-eabi- respectively. Click 'Apply and Close' to finish up the setting.
At this point, the project is buildable in Eclipse now.
To build the project, simply right click on the project and select 'Build Project.' If needed, select 'Clean Project' to clean up the project first.
The build log is shown in the window 'Console.'
Symbol Resolution and Indexing
Eclipse does NOT use Makefile for indexing and symbol resolution. To have Eclipse to resolve and index the symbols in the imported project, here are the steps to achieve this:
- Download the pre-configured xml file according to the SDK revision and modify the path where the toolchain is installed. See the highlighted lines in the screenshot of ambiqsuiter4_ap4_eclipse_paths_and_symbols_settings.xml below.
- Import the xml to the project by right clicking on the project name and navigating to 'Properties.' In the section 'C/C++ General', select 'Paths and Symbols.' Import the xml file by clicking 'Import Settings...' on the bottom left corner of the tab. Then click 'Apply and Close.' The included directories shall be listed after a successful import.
- The attached xmls are the base settings based on the example project ble_freertos_fit. Any left directories can be added manually by clicking 'Add...' on the right.
- Right click on the project again and navigate to 'Index/Rebuild.' Then all the symbols shall be resolved now but one resolving error, 'arm-none-eabi-echo not found in PATH.' This error is harmless and can be left.
AmbiqSuite R4: ambiqsuiter4_ap4_eclipse_paths_and_symbols_settings.xml for Apollo4/Apollo4Blue
AmbiqSuite R4: ambiqsuiter4_ap4p_eclipse_paths_and_symbols_settings.xml for Apollo4 Plus/Apollo4Blue Plus
AmbiqSuite R3: ambiqsuiter3_eclipse_paths_and_symbols_settings.xml
For the first time to debug the project in Eclipse, a debug configuration needs to be set up.
- Right click on the project and navigate through 'Debug As/Debug Configurations....'
- Right click on 'GDB SEGGER J-Link Debugger' to create a new configuration.
- In the page 'Main,' the project name and the C/C++ application shall be filled up automatically. If not, fill in the correct name manually.
- Switch to the page 'Debugger.' Make sure the J-Link executable path is resolved correctly. If not, click 'Browse' on the right to configure the correct path.
- Fill up the device name and the CPU frequency. fields with the correct values respectively. Please find the device name and CPU frequency from the article Apollo Family Device Names and 3rd-Party Development Utilities.
- Set up SWO in the page 'Startup.'
- To view peripheral registers in a debugging session, the system view description(SVD) file needs to be imported in the page 'SVD Path.'
- Click 'Debug' to start a debugging session. The page 'Console' shows the SWO log.
- To view the peripheral registers, navigate through 'Window/Show View/Peripherals.' Tick a set of register to be checked, the values will be shown in the page 'Memory.'