diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..d7487ab --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,65 @@ +# libhal starter architecture + +## `src/main.cpp` + +It contains the main loop of the application. In this example, it just prints +"Hello, World" and toggles an LED on and off. This application will reset after +10 iterators just to demonstrate the capability. + +## `include/application.hpp` + +This file defines the `resource_list` structure which holds optional pointers +to the led, console, clock interfaces and reset callback. Modify this structure +to change the set of required drivers, settings, and memory resources for the +application. `initialize_platform` functions that must be implemented in the +`platform/` file. + +## `CMakeLists.txt` + +This is the build file for the project. It sets the minimum required version of +CMake, names the project, and sets the platform library. It also defines the +sources to compile and the libraries to link against. Finally, it sets up the +post-build steps with `libhal_post_build`. + +### Profile Environment Variables + +At the start of the cmake file you will encounter these lines: + +```cmake +# Always check that the $ENV{LIBHAL_PLATFORM_LIBRARY} & $ENV{LIBHAL_PLATFORM} +# environment variables are set by the profile. +if("$ENV{LIBHAL_PLATFORM_LIBRARY}" STREQUAL "") + message(FATAL_ERROR + "Build environment variable LIBHAL_PLATFORM_LIBRARY is required for " "this project.") +endif() +if("$ENV{LIBHAL_PLATFORM}" STREQUAL "") + message(FATAL_ERROR + "Build environment variable LIBHAL_PLATFORM is required for " + "this project.") +endif() +``` + +libhal conan profiles utilize environment variables as a generic means to +communicate to build systems the name of the libhal binary package, +`$ENV{LIBHAL_PLATFORM_LIBRARY}` and the name of the target platform +`$ENV{LIBHAL_PLATFORM}`. If the developer wishes to use a different build +system compatible with conan, they will need to use their build system's means +to acquire environment variables in order link against the correct library and +select the correct platform source file. + +## `platforms/lpc4078.cpp` + +This file provides an implementation for `initialize_platform`, for the +`LPC4078` platform. In `initialize_platform`, it sets the clock speed, +configures a uart peripheral for console output, and sets up an output pin for +the led. Each driver is statically allocated. The returned `resource_list` has +the pointers to each statically allocated peripheral and a reset callback that +can resets the microcontroller. + +### `platforms/*.cpp` + +Just like `platforms/lpc4078.cpp` but for any other platforms. It's important +to note that the specifics of the `initialize_platform` function and the +peripherals used will likely vary between different platforms but sometimes +they don't. As an example the `lpc4074.cpp` file just includes directly the +`lpc4078.cpp` because those are identical. diff --git a/CMakeLists.txt b/CMakeLists.txt index 54ea3b4..983421d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -16,32 +16,30 @@ cmake_minimum_required(VERSION 3.25) project(app.elf LANGUAGES CXX) -set(platform_library $ENV{LIBHAL_PLATFORM_LIBRARY}) -set(platform $ENV{LIBHAL_PLATFORM}) - -if("${platform_library}" STREQUAL "") +# Always check that the $ENV{LIBHAL_PLATFORM_LIBRARY} & $ENV{LIBHAL_PLATFORM} +# environment variables are set by the profile. +if("$ENV{LIBHAL_PLATFORM_LIBRARY}" STREQUAL "") message(FATAL_ERROR "Build environment variable LIBHAL_PLATFORM_LIBRARY is required for " "this project.") endif() - -if("${platform}" STREQUAL "") +if("$ENV{LIBHAL_PLATFORM}" STREQUAL "") message(FATAL_ERROR "Build environment variable LIBHAL_PLATFORM is required for " "this project.") endif() -find_package(libhal-${platform_library} REQUIRED CONFIG) +find_package(libhal-$ENV{LIBHAL_PLATFORM_LIBRARY} REQUIRED CONFIG) find_package(libhal-util REQUIRED CONFIG) add_executable(${PROJECT_NAME} src/main.cpp - platforms/${platform}.cpp + platforms/$ENV{LIBHAL_PLATFORM}.cpp ) target_compile_options(${PROJECT_NAME} PRIVATE -g -Wall -Wextra --save-temps) target_include_directories(${PROJECT_NAME} PUBLIC include .) target_link_libraries(${PROJECT_NAME} PRIVATE - libhal::${platform_library} + libhal::$ENV{LIBHAL_PLATFORM_LIBRARY} libhal::util) libhal_post_build(${PROJECT_NAME}) diff --git a/README.md b/README.md index f4c7e4e..7cf0466 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,23 @@ # libhal-starter Before getting started, if you haven't used libhal before, follow the -[Getting Started](https://libhal.github.io/getting_started/) guide. +[Getting Started](https://libhal.github.io/latest/getting_started/) guide. + +## 📥 Installing Platform Profiles + +For ARM MCU profiles: + +```bash +conan config install -sf conan/profiles/v1 -tf profiles https://github.com/libhal/libhal-arm-mcu.git +``` + +`micromod` profiles: + +```bash +conan config install -sf conan/profiles/v1 -tf profiles https://github.com/libhal/libhal-micromod.git +``` + +## 🏗️ Building Application To build the project: @@ -21,7 +37,7 @@ For the STM32F103 MicroMod V4: conan build . -pr mod-stm32f1-v4 -pr arm-gcc-12.3 ``` -## Supported platforms +## ✅ Supported platforms - lpc4078 - lpc4074 @@ -29,45 +45,8 @@ conan build . -pr mod-stm32f1-v4 -pr arm-gcc-12.3 - micromod - lpc4078 MicroMod V5 - stm32f103c8 MicroMod V4 - - stm32f103c8 MicroMod V5 - -## Installing Platform Profiles - -For ARM MCU profiles: -```bash -conan config install -sf conan/profiles/v1 -tf profiles https://github.com/libhal/libhal-arm-mcu.git -``` - -`micromod` profiles: - -```bash -conan config install -sf conan/profiles/v1 -tf profiles https://github.com/libhal/libhal-micromod.git -``` +## 🤔 Wondering how is this repo organized? -## Description of Files - -1. `main.cpp`: It contains the main loop of the application. In this - example, it just prints "Hello, World" and toggles an LED on and off. This - application will reset after 10 iterators just to demonstrate the capability. -2. `application.hpp`: This file defines the `resource_list` structure which - holds optional pointers to the led, console, clock interfaces and reset - callback. Modify this structure to change the set of required drivers, - settings, and memory resources for the application. `initialize_platform` - functions that must be implemented in the `platform/` file. -3. `CMakeLists.txt`: This is the build file for the project. It sets the minimum - required version of CMake, names the project, and sets the platform library. - It also defines the sources to compile and the libraries to link against. - Finally, it sets up the post-build steps with `libhal_post_build`. -4. `platforms/lpc4078.cpp`: This file provides an implementation for - `initialize_platform`, for the LPC4078 platform. In `initialize_platform`, - it sets the clock speed, configures a uart peripheral for console output, - and sets up an output pin for the led. Each driver is statically allocated. - The returned `resource_list` has the pointers to each statically allocated - peripheral and a reset callback that can resets the microcontroller. -5. `platforms/*.cpp`: Just like `platforms/lpc4078.cpp` but for any other - platforms. It's important to note that the specifics of the - `initialize_platform` function and the peripherals used will likely vary - between different platforms but sometimes they don't. As an example the - `lpc4074.cpp` file just includes directly the `lpc4078.cpp` because those - are identical. +See our [`ARCHITECTURE.md`](./ARCHITECTURE.md) to learn about the important +files in the project, what they do, and quirks about how they work.