notes.txt

NOTES

---
These are just running notes, or what the Rubber Duck would hear.
They don't have to make sense, but could still be useful.
---

Principles:
    The library provides parts only
    The project puts them together
    The project is driving the library
    The library is not driving the project
    The library makes no assumptions about the project

Decisions:
    The library is built together with the project?
        - No, too much 
OR
    The library is built separately with appropriate parameters.
    The project can be built with other parameters.
    We build library once, as we need it, and we can share it between projects
        - YES
OR
    We build the library together with the project, but in the project directory
    I.e. one library build per project
        - No, too much build overhead

The library accepts the following when building:
    ...

The problem could be that files for some targets can only be compiled with
certain options. The solution could be providing a separate Makefile for each
target to build the library with default options set.

Then how do we build the library with support for multiple targets?

If they're compatible, they would share common pieces of Makefiles

------
We don't want to have the target's name in header paths when using the
library, because that could lead to issues when switching the target in a
project. E.g. when some file is not updated to point to the new target's
header.

I.e. we don't want to have to write this in projects using the library:

    #include <stm32f103c8t6/gpio.h>

We want to write this:

    #include <gpio.h>

And have the path to the headers specified with -I.

In general, we want to point to a particular subdir of the library we want to
use with -I and -L.

However, how are we then going to do the library's internal includes?
Relative paths, perhaps?
------
How can we let users include header files from more general directories. E.g.
when the user is building and using the stm32f103c8t6 target, and some files
are defined at the stm32f level. Let's say gpio.h is there, and the user wants
to include it with "#include <gpio.h>". How do we make sure that can happen?

- We make the users specify all the directories leading to the specific
  directory using the -I option. Inconvenient, forces the user to find out
  what's required, and easy to get wrong and get out-of-sync.

- We put (links to) all files into each specific directory. Perhaps
  automatically, at build time? But for the start manually?
  Let's try that.

----
How are we going to maintain the inheritance VS consistent user API?
I.e. how do we maintain the hardware abstraction layer (HAL)?

A parent implements only the features common across its children. Each child
implements its own idiosyncrasies. And so on. They're all different. What
we're building here is just a translation of the reference documentation to a
C API, with minimal modification. Where should the HAL live?

First of all, each of the target-specific libraries should also deal with
translating their HW API to the HAL API. They should also define which parts
of the HAL API are available. In the simplest implementation, they could
simply provide the headers defining interfaces identical to all other targets.

However, how do we make sure that each of those is a subset of the expected
HAL, the standard HAL? Can we e.g. include each of the corresponding headers
and let the compiler complain if the redefinitions don't match?

Oh, how about we just include all the headers with matching names and let the
compiler complain if there are mismatches? Wow, sounds great! We just need to
make sure they use different header guard macros. Copy-pasting those
declarations around wouldn't be fun, though. Perhaps we can have common
headers, which we reuse for some of those common definitions.
----
Another thing about HAL: how do we separate private target-specific
declarations from HAL? Do we have specially-named headers? Put them into .c
files for HAL implementation directly?