Miosix and git workflow - Revision history

Fede.tft at 07:18, 17 May 2026

2026-05-17T07:18:01Z

← Older revision		Revision as of 07:18, 17 May 2026
Line 119:		Line 119:
	First, copy the ''miosix-kernel/miosix/config'' directory to your project.		First, copy the ''miosix-kernel/miosix/config'' directory to your project.

	Second, copy a template form the ''miosix-kernel/templates'' directory to your project. The ''simple'' template configures the kernel as a unikernel and will run your application in kernelspace. The ''processes'' template will allow you to develop (part of) your application in a userspace process with memory protection, bu that's a more advanced topic ~~realted~~ to the [[~~fliod~~ kernel]] concept.		Second, copy a template form the ''miosix-kernel/templates'' directory to your project. The ''simple'' template configures the kernel as a unikernel and will run your application in kernelspace. The ''processes'' template will allow you to develop (part of) your application in a userspace process with memory protection, bu that's a more advanced topic related to the [[fluid kernel]] concept.

	You shouldn't copy the template directory, rather its content, so the ''main.cpp'', ''Makefile'' and ''CMakeLists.txt'' files in the case of the ''simple'' template.		You shouldn't copy the template directory, rather its content, so the ''main.cpp'', ''Makefile'' and ''CMakeLists.txt'' files in the case of the ''simple'' template.

Fede.tft at 14:52, 15 May 2026

2026-05-15T14:52:00Z

@@ Line 108: / Line 108: @@
 and your project should now contain the ''config'' directory and the ''main.cpp'', ''Makefile'' and ''CMakeLists.txt'' files.
 === Manually copying a template ===
 = Forking the Miosix git repository =

Fede.tft at 14:34, 15 May 2026

2026-05-15T14:34:44Z

Show changes

Fede.tft at 09:44, 15 May 2026

2026-05-15T09:44:27Z

@@ Line 85: / Line 85: @@
 The [https://github.com/fedetft/miosix-kernel/blob/master/README.md README.md] file contains more detailed information on how the kernel source code directory tree is structured, but a quick overview is that the entire kernel code is in the ''miosix'' subdirectory, ''templates'' contains application templates you can copy out of the kernel directory to create your out of tree projects, ''examples'' contains some demos of the Miosix APIs, wile ''tools'' contains scripts and support code that does not get compiled into the kernel. It also contains the scripts and patches used to build the [[Miosix Toolchain]], the GCC-based cross compiler used to build the kernel.
-=== Making changes ===
+Once you start making changes you can simply commit in the cloned git repository. If you need to share your changes, perhaps because there are multiple developers, git allows to have multiple remotes for a repository, so you can leave the default remote to periodically pull updates and bugfixes from the upstream Miosix repository, as well as push and pull from your personal remote repository.
-Once you start making changes you can simply commit in the cloned git repository. If you need to share your changes, perhaps because there are multiple developers, git allows to have multiple remotes for a repository, so you can leave the default remote to periodically pull updates and bugfixes from the upstream Miosix repository, as well as push and pull from your personal remote repository.
+== Running the Miosix regression testsuite ==
 == Contributing to Miosix ==
@@ Line 126: / Line 162: @@
 If you wrote the file you want to add from scratch, just add your name to the copyright notice. If instead you copy-pasted the file from another one already present in the kernel and modified it (this often happens when making BSPs as there's almost always a similar BSP in the kernel to take inspiration from), just append your name to the list of authors of the file you copied.
 Since we use github only as a mirror to our repository that we host on miosix.org, we do not accept pull requests. You will instead be required to make a [https://git-scm.com/docs/git-format-patch format-patch] with the changes you want to be pushed upstream and send it via email to fede.tft&&miosix.org (s/&&/@/). It may be a good idea to get in contact first to discuss the changes you want pushed upstream, especially if they include modifications to the kernel itself rather than being simply new BSPs.

Fede.tft at 08:56, 15 May 2026

2026-05-15T08:56:53Z

Show changes

Fede.tft at 08:15, 15 May 2026

2026-05-15T08:15:52Z

← Older revision		Revision as of 08:15, 15 May 2026
Line 41:		Line 41:
	Out of git tree projects allow you to write applications in a directory that stays separate from the Miosix kernel directory. Additionally, they allow to perform the kernel configuration (that requires editing configuration files) without the need to make changes to files within the Miosix git repo ''at all''. This last point is important both to have the Miosix git repository as a [http://www.git-scm.com/book/en/Git-Tools-Submodules git submodule] of your application's git repository, and to allow sharing the same downloaded copy of the Miosix kernel across different applications, each with its own configuration. The kernel source code size on the hard drive has grown bigger in recent years due to the inclusion of headers with peripheral registers definitions in the [https://github.com/fedetft/miosix-kernel/tree/master/miosix/arch/CMSIS CMSIS] directory, so you may want to share a single downloaded copy of the kernel across several projects.		Out of git tree projects allow you to write applications in a directory that stays separate from the Miosix kernel directory. Additionally, they allow to perform the kernel configuration (that requires editing configuration files) without the need to make changes to files within the Miosix git repo ''at all''. This last point is important both to have the Miosix git repository as a [http://www.git-scm.com/book/en/Git-Tools-Submodules git submodule] of your application's git repository, and to allow sharing the same downloaded copy of the Miosix kernel across different applications, each with its own configuration. The kernel source code size on the hard drive has grown bigger in recent years due to the inclusion of headers with peripheral registers definitions in the [https://github.com/fedetft/miosix-kernel/tree/master/miosix/arch/CMSIS CMSIS] directory, so you may want to share a single downloaded copy of the kernel across several projects.

	Note that the ability to develop applications without making changes to the kernel directory is currently limited to the use case of configuring the kernel for one of the available BSPs. If you need to add BSPs to the kernel, then you'll most likely also have to fork the kernel repository. The ''most likely'' is due to ''generic'' BSPs in the kernel (which can be identified in the list of ~~board~~ as ''<chip name>_generic'' such as ''stm32f103xb_generic''). If you're writing an application for a board that has a chip with a generic BSP in the kernel, you can (unless you ''really'' need to run some custom code during boot) get away with selecting the generic BSP ~~even though the board you're developing for has not BSP in~~ the kernel. If there's no generic BSP for your chip, or need to add support for an entirely new chip, then you'll have to fork the kernel to add it.		Note that the ability to develop applications without making changes to the kernel directory is currently limited to the use case of configuring the kernel for one of the available BSPs. If you need to add BSPs to the kernel, then you'll most likely also have to fork the kernel repository. The ''most likely'' is due to ''generic'' BSPs in the kernel, which can be identified in the list of boards in [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc Makefile.inc] as ''<chip name>_generic'' such as ''stm32f103xb_generic''. If you're writing an application for a board that has a chip with a generic BSP in the kernel, you can (unless you ''really'' need to run some custom code during boot) get away with selecting the generic BSP without forking the kernel. If there's no generic BSP for your chip, or need to add support for an entirely new chip, then you'll have to fork the kernel to add it.

	Suppose you have a git repository called test, which is the repo of your application, and you would like to download the miosix-kernel repository as a git submodule. Then open a shell in the test repository and type		Suppose you have a git repository called test, which is the repo of your application, and you would like to download the miosix-kernel repository as a git submodule. Then open a shell in the test repository and type

Fede.tft at 08:13, 15 May 2026

2026-05-15T08:13:20Z

← Older revision		Revision as of 08:13, 15 May 2026
Line 39:		Line 39:
	== Setting up an out of git tree project ==		== Setting up an out of git tree project ==

	Out of git tree projects allow you to write applications in a directory that stays separate from the Miosix kernel directory. Additionally, they allow to perform the kernel configuration (that requires editing configuration files) without the need to make changes to files within the Miosix git repo ''at all''. This last point is important both to have the Miosix git repository as a [http://www.git-scm.com/book/en/Git-Tools-Submodules git submodule] of your application's git repository, ad to allow sharing the same downloaded copy of the Miosix kernel across different applications, each with its own configuration. The kernel source code size on the hard drive has grown bigger in recent years due to the inclusion of headers with peripheral registers definitions in the [https://github.com/fedetft/miosix-kernel/tree/master/miosix/arch/CMSIS CMSIS] directory, so you may want to share a single downloaded copy of the kernel across several projects.		Out of git tree projects allow you to write applications in a directory that stays separate from the Miosix kernel directory. Additionally, they allow to perform the kernel configuration (that requires editing configuration files) without the need to make changes to files within the Miosix git repo ''at all''. This last point is important both to have the Miosix git repository as a [http://www.git-scm.com/book/en/Git-Tools-Submodules git submodule] of your application's git repository, and to allow sharing the same downloaded copy of the Miosix kernel across different applications, each with its own configuration. The kernel source code size on the hard drive has grown bigger in recent years due to the inclusion of headers with peripheral registers definitions in the [https://github.com/fedetft/miosix-kernel/tree/master/miosix/arch/CMSIS CMSIS] directory, so you may want to share a single downloaded copy of the kernel across several projects.

	Note that the ability to develop applications without making changes to the kernel directory is currently limited to the use case of configuring the kernel for one of the available BSPs. If you need to add BSPs to the kernel, then you'll most likely also have to fork the kernel repository. The ''most likely'' is due to ''generic'' BSPs in the kernel (which can be identified in the list of board as ''<chip name>_generic'' such as ''stm32f103xb_generic''). If you're writing an application for a board that has a chip with a generic BSP in the kernel, you can (unless you ''really'' need to run some custom code during boot) get away with selecting the generic BSP even though the board you're developing for has not BSP in the kernel. If there's no generic BSP for your chip, or need to add support for an entirely new chip, then you'll have to fork the kernel to add it.		Note that the ability to develop applications without making changes to the kernel directory is currently limited to the use case of configuring the kernel for one of the available BSPs. If you need to add BSPs to the kernel, then you'll most likely also have to fork the kernel repository. The ''most likely'' is due to ''generic'' BSPs in the kernel (which can be identified in the list of board as ''<chip name>_generic'' such as ''stm32f103xb_generic''). If you're writing an application for a board that has a chip with a generic BSP in the kernel, you can (unless you ''really'' need to run some custom code during boot) get away with selecting the generic BSP even though the board you're developing for has not BSP in the kernel. If there's no generic BSP for your chip, or need to add support for an entirely new chip, then you'll have to fork the kernel to add it.

Fede.tft at 08:09, 15 May 2026

2026-05-15T08:09:25Z

← Older revision		Revision as of 08:09, 15 May 2026
Line 39:		Line 39:
	== Setting up an out of git tree project ==		== Setting up an out of git tree project ==

	Out of git tree projects allow you to write applications in a directory that stays separate from the Miosix kernel directory. Additionally, ~~it allows~~ to perform the kernel configuration (that requires editing configuration files) without the need to make changes to files within the Miosix git repo ''at all''. This last point is important both to have the ~~miosix~~ git repository as a [http://www.git-scm.com/book/en/Git-Tools-Submodules git submodule] of your application's git repository, ad to allow sharing the same downloaded copy of the Miosix kernel across different applications, each with its own configuration.		Out of git tree projects allow you to write applications in a directory that stays separate from the Miosix kernel directory. Additionally, they allow to perform the kernel configuration (that requires editing configuration files) without the need to make changes to files within the Miosix git repo ''at all''. This last point is important both to have the Miosix git repository as a [http://www.git-scm.com/book/en/Git-Tools-Submodules git submodule] of your application's git repository, ad to allow sharing the same downloaded copy of the Miosix kernel across different applications, each with its own configuration. The kernel source code size on the hard drive has grown bigger in recent years due to the inclusion of headers with peripheral registers definitions in the [https://github.com/fedetft/miosix-kernel/tree/master/miosix/arch/CMSIS CMSIS] directory, so you may want to share a single downloaded copy of the kernel across several projects.

	Note that the ability to develop applications without making changes to the kernel directory is currently limited to the use case of configuring the kernel for one of the available BSPs. If you need to add BSPs to the kernel, then you'll most likely also have to fork the kernel repository. The ''most likely'' is due to ''generic'' BSPs in the kernel (which can be identified in the list of board as ''<chip name>_generic'' such as ''stm32f103xb_generic''). If you're writing an application for a board that has a chip with a generic BSP in the kernel, you can (unless you ''really'' need to run some custom code during boot) get away with selecting the generic BSP even though the board you're developing for has not BSP in the kernel. If there's no generic BSP for your chip, or need to add support for an entirely new chip, then you'll have to fork the kernel to add it.		Note that the ability to develop applications without making changes to the kernel directory is currently limited to the use case of configuring the kernel for one of the available BSPs. If you need to add BSPs to the kernel, then you'll most likely also have to fork the kernel repository. The ''most likely'' is due to ''generic'' BSPs in the kernel (which can be identified in the list of board as ''<chip name>_generic'' such as ''stm32f103xb_generic''). If you're writing an application for a board that has a chip with a generic BSP in the kernel, you can (unless you ''really'' need to run some custom code during boot) get away with selecting the generic BSP even though the board you're developing for has not BSP in the kernel. If there's no generic BSP for your chip, or need to add support for an entirely new chip, then you'll have to fork the kernel to add it.

Fede.tft at 08:05, 15 May 2026

2026-05-15T08:05:27Z

← Older revision		Revision as of 08:05, 15 May 2026
Line 39:		Line 39:
	== Setting up an out of git tree project ==		== Setting up an out of git tree project ==

	Out of git tree projects allow to write ~~your application~~ in ~~your~~ directory that stays separate from the Miosix kernel directory. Additionally, it allows to perform the kernel configuration (that requires editing configuration files) without the need to make changes to files within the Miosix git repo ''at all''. This last point is important both to have the miosix git repository as a [http://www.git-scm.com/book/en/Git-Tools-Submodules git submodule] of your application's git repository, ad to allow sharing the same downloaded copy of the Miosix kernel across different applications, each with its own configuration.		Out of git tree projects allow you to write applications in a directory that stays separate from the Miosix kernel directory. Additionally, it allows to perform the kernel configuration (that requires editing configuration files) without the need to make changes to files within the Miosix git repo ''at all''. This last point is important both to have the miosix git repository as a [http://www.git-scm.com/book/en/Git-Tools-Submodules git submodule] of your application's git repository, ad to allow sharing the same downloaded copy of the Miosix kernel across different applications, each with its own configuration.

	Note that the ability to develop applications without making changes to the kernel directory is currently limited to the use case of configuring the kernel for one of the available BSPs. If you need to add BSPs to the kernel, then you'll most likely also have to fork the kernel repository. The ''most likely'' is due to ''generic'' BSPs in the kernel (which can be identified in the list of board as ''<chip name>_generic'' such as ''stm32f103xb_generic''). If you're writing an application for a board that has a chip with a generic BSP in the kernel, you can (unless you ''really'' need to run some custom code during boot) get away with selecting the generic BSP even though the board you're developing for has not BSP in the kernel. If there's no generic BSP for your chip, or need to add support for an entirely new chip, then you'll have to fork the kernel to add it.		Note that the ability to develop applications without making changes to the kernel directory is currently limited to the use case of configuring the kernel for one of the available BSPs. If you need to add BSPs to the kernel, then you'll most likely also have to fork the kernel repository. The ''most likely'' is due to ''generic'' BSPs in the kernel (which can be identified in the list of board as ''<chip name>_generic'' such as ''stm32f103xb_generic''). If you're writing an application for a board that has a chip with a generic BSP in the kernel, you can (unless you ''really'' need to run some custom code during boot) get away with selecting the generic BSP even though the board you're developing for has not BSP in the kernel. If there's no generic BSP for your chip, or need to add support for an entirely new chip, then you'll have to fork the kernel to add it.

Fede.tft at 08:04, 15 May 2026

2026-05-15T08:04:41Z

← Older revision		Revision as of 08:04, 15 May 2026
Line 39:		Line 39:
	== Setting up an out of git tree project ==		== Setting up an out of git tree project ==

	Out of git tree projects allow to write your application ~~outside~~ the Miosix ~~top-level~~ directory, without the need to make changes to files within the Miosix git repo ''at all''. This ~~allows to separate your application from Miosix, and was designed~~ to have the miosix git repository as a [http://www.git-scm.com/book/en/Git-Tools-Submodules git submodule] of your application's git repository. ~~This~~ also ~~allows~~ to ~~not have~~ the ~~source files~~ of ~~your~~ application ~~under any version control system~~, even though ~~these days if~~ you're ~~writing code without a version control system~~ you ~~are really missing something~~.		Out of git tree projects allow to write your application in your directory that stays separate from the Miosix kernel directory. Additionally, it allows to perform the kernel configuration (that requires editing configuration files) without the need to make changes to files within the Miosix git repo ''at all''. This last point is important both to have the miosix git repository as a [http://www.git-scm.com/book/en/Git-Tools-Submodules git submodule] of your application's git repository, ad to allow sharing the same downloaded copy of the Miosix kernel across different applications, each with its own configuration.

			Note that the ability to develop applications without making changes to the kernel directory is currently limited to the use case of configuring the kernel for one of the available BSPs. If you need to add BSPs to the kernel, then you'll most likely also have to fork the kernel repository. The ''most likely'' is due to ''generic'' BSPs in the kernel (which can be identified in the list of board as ''<chip name>_generic'' such as ''stm32f103xb_generic''). If you're writing an application for a board that has a chip with a generic BSP in the kernel, you can (unless you ''really'' need to run some custom code during boot) get away with selecting the generic BSP even though the board you're developing for has not BSP in the kernel. If there's no generic BSP for your chip, or need to add support for an entirely new chip, then you'll have to fork the kernel to add it.

	Suppose you have a git repository called test, which is the repo of your application, and you would like to download the miosix-kernel repository as a git submodule. Then open a shell in the test repository and type		Suppose you have a git repository called test, which is the repo of your application, and you would like to download the miosix-kernel repository as a git submodule. Then open a shell in the test repository and type