Document stand-alone build using cmake

[nasa]

Document stand-alone build using cmake

[skliper]

"stand-alone" OSAL concept doesn't really exist anymore. Build system does build osal and functional tests. The cFS 6.7 VDD (currently at https://github.com/nasa/cFS/blob/dev-vdd/VDD.md but will go with official release documentation) does describe method to coverage test OSAL. Note the desire is to integrate the coverage testing with the standard build eventually (depends on a few updates in progress.)

Closing as duplicate since work is done elsewhere.

[skliper]

See also nasa/cFE#386

[jphickey]

"stand-alone" OSAL concept doesn't really exist anymore.

As of the most recent discussions on this I had thought that stand alone OSAL was still a supported thing. OSAL can certainly be built "stand-alone" outside of CFE/CFS in the current build. It is just a matter of invoking cmake and supplying the right config values (OSAL_SYSTEM_OSTYPE, OSAL_SYSTEM_BSPTYPE, and path to your osconfig.h). This standalone build was verified by the old bamboo system and I also build it this way occasionally to confirm that it still works.

Care was taken in the past to ensure that there are no dependencies on CFE in the OSAL, only dependencies on OSAL in CFE, such that OSAL can still be used outside of the CFE/CFS world.

[skliper]

From your email on 9/19/19 below (mostly 2nd paragraph), in that OSAL is an embedded library, and "can't be a true standalone build" due to the osconfig.h issue you brought up. Either we call it a stand alone build or we don't, please pick one so we can use common terminology moving forward. Either way the desire is still to integrate the coverage tests with the build system, so I'd expect the "example" case for building and linking against the OSAL embedded library (without the rest of cFE) will be implemented.

To build OSAL as a standalone library, you just follow the standard procedure for any CMake-based project. The OSAL_SYSTEM_OSTYPE and OSAL_SYSTEM_BSPTYPE variables indicate the type of OS and BSP to build for, respectively, just as they do for CFE. If you specify ENABLE_UNIT_TESTS=TRUE, then you’ll also build the tests. (but these are not the coverage aka “unit” tests, these are the functional tests).

To be clear though, building OSAL “standalone” is really just a development exercise to confirm that it works and ensure it doesn’t depend on any bits of CFE. OSAL is an embedded library at its nature so if it is not used with CFE then it would be integrated into the build of a some other larger app, as a dependent/component library, much in the same way as CFE does it (i.e. call add_subdirectory from the parent CMake).

The major thing that makes it so it can’t be a true standalone build is the osconfig.h – dependencies on this config tend to leak out into the ABI – which basically just means that the application needs to be built with the exact same osconfig.h that OSAL itself was built with, or else risk breakage. If it had a stable ABI independent of osconfig.h, then OSAL could actually be built once and then just linked to. But as it stands I would never recommend someone do this; they should build the library with their application to be safe.

[jphickey]

OK, yes I concur we need to define what is meant by "stand-alone" here. The context is a little different and hence the confusion. The two concerns are:

1. Building OSAL directly by itself, nothing else.
2. Building & linking OSAL to support an embedded application other than CFE.

In this context, I interpret "standalone" to simply mean that the library can be built outside of CFE, yielding "libosal.a" and "libosal_bsp.a" binary files as artifacts (item 1 above).

The previous email is more of pragmatic one, and relates to item 2 above, where although it is possible to build the OSAL library outside of a larger application, it would NOT be a recommended practice for real deployments, because the configuration needs to be tuned to the target at compile time (via osconfig.h) and this also affects the resultant ABI.

So to summarize - The intent/goal here is that OSAL may be used with applications other than CFE/CFS. Building OSAL by itself (item 1 above), although impractical for real deployment, is effective at ensuring no unexpected CFE dependencies (or other improper assumptions) creep into the OSAL build script. This is a way to gain confidence that a 3rd party non-CFE application will also work as expected.

Basically, item 1 above could be considered a prerequisite to item 2 above, so it does make sense to verify that it works as a sort of "least common denominator". And it is fairly simple/straightforward to do this in CI, by supplying an example osconfig.h file along with setting OSAL_SYSTEM_OSTYPE and OSAL_SYSTEM_BSPTYPE` build variables.

Does this make sense?

[jphickey]

As another note - the "standalone" OSAL build with ENABLE_UNIT_TESTS=TRUE switch also presents a useful way to build and verify all the OSAL unit tests, in isolation, independent of any application.

This alone is worthwhile.

[skliper]

I concur w/ adding item 1 to CI. The intent of my original comment was not to say we didn't support this.

How about also also consolidating around a single sample osconfig.h vs providing one for each bsp deep in the directory structure? Might have more luck keeping one version up to date (and note different options based on the different OS's), vs keeping all three synced (except where they are different).

Or could just grab the one from cFE sample_defs, but that adds an external dependence. Could flip it and get the single sample osconfig.h from OSAL as part of cFE configuration instead of including it as part of the cFE repo in cfe/make/sample_defs, so then we'd be back to just one copy, and it'd be owned by the OSAL repo. Really more of a configuration pattern it would help to clarify for both apps and OSAL, vs maintaining multiple copies in multiple repos, some of which seldom get used and rot or diverge as updates/clarifications are made. Bigger can of worms we've touched on multiple times in the past.