sysbuild: support SysbuildLists.txt as entry point and support APPLICATION_CONFIG_DIR

[tejlmand]

This PR refactors sysbuild entry code by creating a CMake sysbuild module for image processing and place sysbuild entry code in a SysbuildLists.txt file.

The SysbuildLists.txt file will be use as template for applications which doesn't provide their own entry file.

An application may place a SysbuildLists.txt file at its toplevel folder. The SysbuildLists.txt file is similar in nature to the CMakeLists.txt file for the application and allows application developers to adjust how an application is built with sysbuild.

Also part of this PR is APPLICATION_CONFIG_DIR support in sysbuild.

---

Additional background info

The name SysbuildLists.txt is proposed as it allows the file to be placed at the sample's top-level folder, next to the CMakeLists.txt. Also the name reflects the intention of the file. However, one implication is that the file is included using include() statement inside sysbuild, meaning the use of add_subdirectory() must include bin dir, like this:

https://github.com/zephyrproject-rtos/zephyr/blob/1f494ea61a401af32d42264e6b75e9eee1a29dc6/share/sysbuild/SysbuildLists.txt#L10-L12

An alternative to SysbuildLists.txt could be a subfolder, like <sample>/sysbuild/CMakeLists.txt, but that makes it less visible as well as less clear of the intention (being entry point for sysbuild).

[tejlmand]

Seems to completely break things, without:

Not broken, but sysbuild itself was looking up a toolchain (which isn't needed because sysbuild itself doesn't compile any code) So this was only a cosmetic issue, albeit a confusing one.

Notice the lines above which are identifying the correct toolchain used for the image build.

Fixed by restoring LANGUAGES <empty> in sysbuild which somehow had disappeared.

[tejlmand]

I like the core proposal, but I don't like the SysbuildLists.txt suggestion.

@57300 Thanks a lot for the feedback. You raise some the same concerns I have, although I ended with a different preference. But i'm open to good arguments. I see pros / cons in both approaches.

• Having to use absolute paths with add_subdirectory() would be annoying. When trying to use a relative path as one would expect, CMake gives no indication that it's relative to share/sysbuild, so it's hard to debug.

I completely agree, and that's why I want to extend the sysbuild_add_subdirectory() to be able to handle this case. This means that sysbuild_add_subdirectory() shall be able to take a relative path and adjust it to APP_DIR, as well as construct the proper bin-dir name, so that user can just do sysbuild_add_subdirectory(<rel-path>) (instead of add_subdirectory(<abs-path> <bin-dir>)).

But a little care must be taken to not introduce unwanted surprises, as well proper behavior on all levels. Hence the reason for leaving this extension to sysbuild_add_subdirectory() out of the initial PR in order to keep focus purely on the overall principle and be able to discuss and decide on the principler and the naming.

• I don't think the name is all that self-explanatory. Considering there's also a sysbuild.cmake that could be placed next to a SysbuildLists.txt, it's not obvious which file would be used for what. It reminds me of how a board directory may contain a board.cmake and a CMakeLists.txt and it's not immediately clear why you'd need both.

But I don't see how the set {sysbuild/CMakeLists.txt, sysbuild.cmake} vs the set {SysbuildLists.txt, sysbuild.cmake} changes that. True, they are not on same level, but the fact that sysbuild/CMakeLists.txt is one level below sysbuild.cmake could make it less intuitive that sysbuild/CMakeLists.txt is actually the entry point, and not sysbuild.cmake. So far, I don't see the comment in favor of one or the other solution. There are two files, and we must clearly describe the difference between those two and when to use which. Regardless of the solution it may not be intuitive to users when to use which one.

• To me, the similarity to CMakeLists.txt also suggests that every sysbuild directory should have a SysbuildLists.txt in it, not just the entry point. Maybe someone would want CMakeLists.txt to only be processed by Zephyr build systems, and SysbuildLists.txt only by sysbuild, which would allow their directory subtrees to overlap (like with CMake and Kconfig), but as of today that's not even possible.

This relates partly to the above reply of sysbuild_add_subdirectory(). We do have the sysbuild_add_subdirectory() which could allow us to prefer SysbuildLists.txt if both SysbuildLists.txt and a CMakeLists.txt exists, and thereby allow directory subtrees to overlap. I initially didn't intend to open this discussion, but if it helps sketch the future direction and helps deciding a direction, then it could be a valuable discussion to have early.

• If we were using Makefiles in Zephyr, would we want to call this a Sysbuildfile?

We would probably name the file Makefile.sysbuild and allow users to invoke using make -f Makefile.sysbuild. Unfortunately CMake doesn't allow us to substitute the name of CMakeLists.txt in similar way as make does 😞

Note, if it purely on the naming, then CMakeLists.sysbuild is also an option, but still suffers the limitation of SysbuildLists.txt.

I think it would be interesting to take it further in the future, by removing the need to go through that file when $APP_DIR/sysbuild/CMakeLists.txt exists, so that this could be used as the sole entry point. Then, sysbuild could be configured by running either:

This is a very good use-case, and could be one which would make the sysbuild/CMakeLists.txt having an edge over the current proposal. But it would mean the sysbuild package would have to be properly exported (if wanting to use the shortcut), but I see that as a minor detail.

---

Extra note, although sysbuild today mainly targets a single board with one or more SoCs, each having one or more CPU clusters, then there is also the use case of building for multiple boards, as discussed: https://github.com/zephyrproject-rtos/zephyr/pull/40555#issuecomment-1165476795

For example one could create a project utilizing SYSBuild to build an audio system consisting of a BLE audio gateway and a headset, each built and flashed to different devices. In such a case, SYSBuild is building and flashing for a system, not just a multi-core SoC.

In the above case, one might create a pure sysbuild project having a SysbuildLists.txt file, but no CMakeLists.txt file because that project cannot be built as a regular Zephyr project (it has no sources) becuase the project is just collect and configuring other projects for a special use-case. In this case, having to create a <highlevel-app>/sysbuild/CMakeLists.txt may not be as clean as just having a <highlevel-app>/SysbuildLists.txt file.

[nordicjm]

I agree with @57300 in that using a standard filename is better <app_dir>/sysbuild/CMakeLists.txt as opposed to SysbuildLists.txt

[57300]

• I don't think the name is all that self-explanatory. Considering there's also a sysbuild.cmake that could be placed next to a SysbuildLists.txt, it's not obvious which file would be used for what. It reminds me of how a board directory may contain a board.cmake and a CMakeLists.txt and it's not immediately clear why you'd need both.

But I don't see how the set {sysbuild/CMakeLists.txt, sysbuild.cmake} vs the set {SysbuildLists.txt, sysbuild.cmake} changes that. True, they are not on same level, but the fact that sysbuild/CMakeLists.txt is one level below sysbuild.cmake could make it less intuitive that sysbuild/CMakeLists.txt is actually the entry point, and not sysbuild.cmake. So far, I don't see the comment in favor of one or the other solution. There are two files, and we must clearly describe the difference between those two and when to use which. Regardless of the solution it may not be intuitive to users when to use which one.

I agree that neither option is truly intuitive and that users will likely have to refer to examples or docs either way. My point is just that I don't believe SysbuildLists.txt (or similar) has a significant advantage in this regard, even though that was the motivation for it as you stated initially. So, you're right in that this comment was not in favor of either solution.

Extra note, although sysbuild today mainly targets a single board with one or more SoCs, each having one or more CPU clusters, then there is also the use case of building for multiple boards, as discussed: #40555 (comment)

(...)

In the above case, one might create a pure sysbuild project having a SysbuildLists.txt file, but no CMakeLists.txt file because that project cannot be built as a regular Zephyr project (it has no sources) becuase the project is just collect and configuring other projects for a special use-case. In this case, having to create a <highlevel-app>/sysbuild/CMakeLists.txt may not be as clean as just having a <highlevel-app>/SysbuildLists.txt file.

For this use case, I think the ideal solution would be to support building without a DEFAULT_IMAGE, so that a dummy CMakeLists.txt could indeed be dropped when not needed. Then, it should be possible to move sysbuild/CMakeLists.txt in its place (one level up) so that we don't depend on this subdirectory for pure sysbuild samples.

All in all, I'm still more interested in the sysbuild/CMakeLists.txt option, but I can address the sysbuild_add_subdirectory() discussion later.

[tejlmand]

My point is just that I don't believe SysbuildLists.txt (or similar) has a significant advantage in this regard, even though that was the motivation for it as you stated initially.

The motivation was between the application dir Zephyr CMakeLists.txt and SysbuildLists.txt. Having both at toplevel application dir makes it more visible that it's an entry point. The naming difference between those clearly indicates which is for Zephyr CMake build and which is for sysbuild.

Not related to the file sysbuild.cmake and SysbuildLists.txt.

Then, it should be possible to move sysbuild/CMakeLists.txt in its place (one level up) so that we don't depend on this subdirectory for pure sysbuild samples.

I could fear that could result in other types of confusion, because in this case you cannot determine by looking at the toplevel folder whether it's a regular Zephyr sample or a dedicated highlevel sysbuild sample.

So even in such a case, then I would prefer to have the sysbuild/CMakeLists.txt for consistency.

[tejlmand]

by @nordicjm

I agree with @57300 in that using a standard filename is better <app_dir>/sysbuild/CMakeLists.txt as opposed to SysbuildLists.txt

by @57300

All in all, I'm still more interested in the sysbuild/CMakeLists.txt option, but I can address the sysbuild_add_subdirectory() discussion later.

will switch to sysbuild/CMakeLists.txt, as I am not against any of the options, just had to open PR with one of them, and there I had a slight preference for a file with a dedicated name related to sysbuild.

[tejlmand]

will switch to sysbuild/CMakeLists.txt

@nordicjm + @57300 done