GitHub folder structure for embedded projects?

[EVblog1]

Hi everyone,

I just created my GitHub account and now I’m planning to put my embedded project there. I’m a bit confused about what the "ideal" folder structure should look like for an embedded project repo.

Should I just dump all source, hardware, document files in one folder, or is it better to separate things?

how you organize your repos so they’re easy for others to understand and contribute to.

[ejeffrey]

Mostly don't sweat it too much.  Reorganizing is only a pain if you are fantastically successful.

But normally people would have a top level README.md file, license files, contribution guidelines, and any any other administrative stuff.  Then a folder for "source" and a folder for "documentation".

If the project has multiple languages or subprojects they can often be different top level folders.  For instance a C/C++ embedded project with python client tools to talk to the embedded system.

[RoGeorge]

It's up to you how you organize/structure your projects.
GitHub won't care, nor object, about how you do that. 

[Siwastaja]

Organization is up to you.

But maybe the most important practical tip would be to create a separate build directory of some sort, and write your makefile (or build script) so that compiler-generated artifacts (like .o files for C/C++ projects) are placed there - and the you add this directory to the .gitignore file, and not push it to Github. i.e., keep your working directories as clean as possible.

Otherwise than that, usually it's a good idea to add directories such as src (for source code), include (for those header files that are used to interface your code from the outside, if applicable), and doc for documentation. Or something similar.

[SiliconWizard]

Oh and thanks for giving your work away to Microsoft and OpenAI!

[EVblog1]

I get your point. For me, the goal is to share the project openly so others can learn from it or build on it  that’s the main reason I’m putting it on GitHub.

I’ll probably just keep it simple: one folder for the source code and another for documentation like schematics and pin information.

[EVblog1]

write your makefile (or build script) so that compiler-generated artifacts (like .o files for C/C++ projects) are placed there

I didn’t quite get your point about writing a makefile.
When I work with PIC, AVR, and 8051, the compiler or IDE already generates the HEX file automatically in its own output folder.

So why would I need to write a makefile ?

[RoGeorge]

If you are new to github, beware that hidden files might upload, too.  Make sure you upload only the necessary files and folders, and not more.

You may want to read about .gitignore for how to configure which files to exclude.  What to exclude depends of the IDE, the programming language, and the other tools you might use with your project.

Most often the hidden files are just configuration files specific to your computer (that are not needed and not wanted by other users, because that might mess their own settings and preferences).  This is not that bad, only an annoyance for other users, but some other times the hidden files might be a personal subscription or encryption keys, or some other files that might contain passwords or other types of personal data.

[Doctorandus_P]

It definitely helps to organize things a bit. Separate directories for firmware, PCB, documentation, but there is no need to overdo it. There are no standards, so just do what seems sensible.

A .gitignore file is certainly useful. Sometimes you can find .gitignore file examples for (sub) projects. For KiCad for example, it excludes all the machine generated stuff such as exported netlists and the whole backups directory. I've seen a bunch of projects that just put the whole KiCad backups directory into GIT.

A very important part that is quite often skipped is to give a decent description of the project. If you've been working on a project for a few months, you know all it's details, but when somebody sees your project for the first time (for example after a search) they may not even know what your project is about, and in what state it is. Is it an initial draft? Does it work? Has it been tested? Is it intended to be a simple toy, or a well thought out work? Adding some files in easily readable formats is also a bonus. For example, it may have a complete (again) KiCad project, but if it also has the schematic as a .pdf file then it's a lot easier and quicker to get an impression of the extent and quality of it.

[Siwastaja]

write your makefile (or build script) so that compiler-generated artifacts (like .o files for C/C++ projects) are placed there

I didn’t quite get your point about writing a makefile.
When I work with PIC, AVR, and 8051, the compiler or IDE already generates the HEX file automatically in its own output folder.

So why would I need to write a makefile ?

So that your life would be much easier than with IDEs, which are constant source of pain and depression as evidenced of multitude of threads. e.g. here.

But if you want to use IDE, then the same idea applies: make sure to configure it so that files that don't need to be versioned (e.g. object files and compiled output) are in a separate directory, which you add to .gitignore.

[radiolistener]

When starting out, don’t overthink the structure - it will naturally evolve as your project grows.

A simple, readable starting point could be:

Code: [Select]

/README.md
/LICENSE
/CMakeLists.txt
/src/            # Firmware source code
/docs/           # Documentation (optional)
/hardware/       # Schematics, PCB layouts, 3D models, etc.
/tests/          # Tests, if any

If it’s just a small single-file project, it’s fine to keep the main file in the root for now.

You can put any garbage into additional sub-folders (docs, hardware, tests, tools, etc.) as it appears - the important part is not to clutter the root directory. As the codebase grows, split src into subfolders like drivers, lib and maybe add an include folder for headers. Keep the repository clean: don’t commit temporary or generated files - use a .gitignore for that.

This way the repo stays understandable to others and easier to maintain over time.

A common and widely accepted build approach is:

Code: [Select]

mkdir build && cd build
cmake ..
make

It’s best to stick with this style for consistency and clarity. So avoid using the folder name "build" for project files, so users can freely use it as the dedicated build directory.

[nctnico]

When starting out, don’t overthink the structure - it will naturally evolve as your project grows.

A simple, readable starting point could be:

Code: [Select]

/README.md
/LICENSE
/CMakeLists.txt
/src/            # Firmware source code
/docs/           # Documentation (optional)
/hardware/       # Schematics, PCB layouts, 3D models, etc.
/tests/          # Tests, if any

If it’s just a small single-file project, it’s fine to keep the main file in the root for now.

You can put any garbage into additional sub-folders (docs, hardware, tests, tools, etc.) as it appears - the important part is not to clutter the root directory. As the codebase grows, split src into subfolders like drivers, lib and maybe add an include folder for headers. Keep the repository clean: don’t commit temporary or generated files - use a .gitignore for that.

This way the repo stays understandable to others and easier to maintain over time.

Agreed. Some people tend to spread files over many directories where many directories only contain 1 file. It totally kills the ability to get a quick overview of a project. Perhaps a good rule of thumb is to only have subdirectories if a directory contains more than 30 files AND there are more than 3 different kind of files.

[radiolistener]

I didn’t quite get your point about writing a makefile.
When I work with PIC, AVR, and 8051, the compiler or IDE already generates the HEX file automatically in its own output folder.

So why would I need to write a makefile ?

An IDE is your personal development environment that automates tasks like code edit, debugging, etc. However, other users may not have, or just don't want to install the same IDE just to build and run your project.

Different developers use various IDE, and some prefer not to use an IDE at all, opting instead to work in a simple text editor and build the code via the command line, as I often do myself. This approach offers a highly flexible, lightweight, and efficient way to build the project.

The purpose of a makefile (CMakeLists.txt or equivalent build script) is to provide a standardized, IDE-independent way to compile your code. Think of the IDE as the tool you use to write and debug, while the makefile defines how the code should be built in any environment.

Don’t assume that everyone who works with your project will have your preferred IDE installed. Some might use a different IDE, or none at all  - they may simply want to build and run your code quickly without the overhead of a full development environment.

Providing a makefile ensures your project is accessible, portable, and easy to build for a wider audience.


Imagine a furniture manufacturer requiring every customer to have their own sawmill, chainsaws, planers, varnishes, and other specialized tools at home just to assemble and use the furniture. That would be highly impractical and limit who can actually use their products.

Similarly, an IDE is a development tool intended for writing and debugging code. The goal is to create code that can be built and used independently of any specific IDE installation, making it accessible to everyone regardless of their chosen tools or environment.

[John Coloccia]

Without going into too much detail, we tend to do:

Code: [Select]

/top_level
    /project_1
        /build //not under CM...this is where build artifacts go
        /module-1
            /src
            /inc
        /module-2
            /src
            /inc
        /prog
            /src
                main.c
        readme
        settings
        makefile
    /project-2
        etc...
    readme
    makefile
    /install //not under CM...this is where we gather the installable images for release

We don't like gathering all the headers in one place. It just makes it harder to reuse modules that are useful. That said, our makefiles do the right thing and add the /inc directories automagically to the include paths.

the /src directory doesn't add much value for most people. We do it for reasons that aren't important here, and I'm toying with the idea of eliminating it because it's maybe not worth it. I wouldn't recommend that as a general rule. Just dump the source files in the module directory.

Any "private" header files go in the source directory and are not accessible to anyone else, unless you explicitly path to it. And if you do that, there's no way in hell you're ever passing a review.