Update OSAL Configuration Guide, build instructions, directory references, etc

[skliper]

Is your feature request related to a problem? Please describe.
Build instructions in doc/OSAL-Configuration-Guide.doc and .pdf have instructions for classic build. Also the section on building the unit tests requires use of the classic build.

Describe the solution you'd like
A new section needs to be written for building unit tests under cmake and the old classic build section needs to be removed (and refs to the classic build in the cmake section need to be stricken.)

Also note in 2.1.1, Setup the OSAL Source Distribution, that the OSAL source distribution directories are not aligned with our current directories. For example, osal/src/make and osal/src/inc no longer exists.

Describe alternatives you've considered
None

Additional context
Related to #339, #351, #194

Requester Info
Chris Knight - NASA/ARC

[davearch]

Hello, adding on to this because I think it may be helpful. I can update documentation too once I figure everything out. I can compile osal using cmake with the ENABLE_UNIT_TESTS set to False. Otherwise I get an error. I've read the whole configuration guide.

Once I got osal compiled I wanted to run the example "tasking-example" but I am not sure how to get that working. Maybe that should be added to the documentation too? The README also mentions it but I don't think that's correct either. I think the documentation refers to a classic build as well because it says I should copy the makefile from the example directory but there isn't one.

I am running a debian 9 VM on Hyper-V. Just to put it out there if I try to compile osal setting the tests to TRUE i get this:
cmake -DOSAL_SYSTEM_OSTYPE=posix -DOSAL_SYSTEM_BSPTYPE=pc-linux -DENABLE_UNIT_TESTS=TRUE -DOSAL_INCLUDEDIR=/home/david/projects/config /home/david/projects/osal
Then I cd into build and make. And I get several lines of nice output but eventually run into this error:
[ 38%] Linking C executable timer-test
/usr/bin/ld: ../libut_bsp.a(bsp_ut.c.o): in function 'main':
bsp_ut.c:(.text+0x669): multiple definition of 'main'; ../libosal.a(bsp_start.c.o):bsp_start.c:(.text+0x0): first defined here
collect2: error: ld returned 1 exit status
make[2]: *** [tests/CMakeFiles/timer-test.dir/build.make:87: tests/timer-test] Error 1
make[1]: *** [CMakeFiles/Makefile2:251: tests/CMakeFiles/timer-test.dir/all] Error 2
make: *** [Makefile:95: all] Error 2

[skliper]

@davearch see also #363, I think @jphickey updates to the BSP may be addressing this

[jphickey]

Yes, there was another report of a similar error on MacOS. Not sure why since this is basically the build we do in CI and it works there? Not clear to me what is different.

Nonetheless, the change I had been working on for #261 will probably improve the situation so I'll work on getting that into a pull request this week.

[davearch]

Okay, weird. Yeah I was certain that I was just doing something wrong. If that's the same command that you all use then something else is going on. To be clear, I am on Windows (on an ASUS ZenBook). So not related to OS X. I'll try to build on something else like my Linux laptop and see what happens.

[davearch]

Sorry to fill up the comments on this issue, I'm not sure if there is a better place to put them. In any case I get the same error output on another laptop of mine that has Debian Linux as it's only OS. I'm not sure if that's helpful.

[skliper]

This is the spot for comments, appreciate the feedback.

Just ran it on our setup (Ubuntu 18.04) and got the same "multiple definition of main" result with the timer-test.

[skliper]

So I do see where from osal the bsp_start.c and bsp_voltab.c get pulled in, but from cFS they don't... I'll see if I can track this down quickly

[skliper]

It's from CMakeLists.txt:

osal/CMakeLists.txt

Lines 109 to 117 in 20a83c4

	set(OSAL_SELECTED_BSPTYPE FALSE)
	if (OSAL_SYSTEM_BSPTYPE AND NOT CFE_SYSTEM_PSPNAME)
	if (IS_DIRECTORY ${OSAL_SOURCE_DIR}/src/bsp/${OSAL_SYSTEM_BSPTYPE})
	set(OSAL_SELECTED_BSPTYPE ${OSAL_SYSTEM_BSPTYPE})
	message(STATUS "OSAL BSP Selection: ${OSAL_SELECTED_BSPTYPE}")
	else()
	message(FATAL_ERROR "Error: ${OSAL_SYSTEM_BSPTYPE} is not a valid BSP")
	endif()
	endif (OSAL_SYSTEM_BSPTYPE AND NOT CFE_SYSTEM_PSPNAME)

and

osal/CMakeLists.txt

Lines 151 to 153 in 20a83c4

	if (OSAL_SELECTED_BSPTYPE)
	aux_source_directory(src/bsp/${OSAL_SELECTED_BSPTYPE}/src BSPFILES)
	endif (OSAL_SELECTED_BSPTYPE)

So if OSAL_SELECTED_BSPTYPE is false, the real bsp isn't included. With the logic in the first blob as it is now, I just set -DCFE_SYSTEM_PSPNAME=whyohwhy and as long as you have an osconfig.h i your search path it should now build.

[skliper]

I suspect this will be cleaned up with the work @jphickey is doing to consolidate bsps, so this should be a short term hack to make it work.

[jphickey]

Confirmed - the pull requests I'm working on submitting (issues #312, #261) will clean this up considerably.

We don't often validate the standalone/non-CFE OSAL build. We should probably have a separate CI script within OSAL to build it separately from CFE. In the meantime I'll also validate the standalone OSAL build with the pull requests I'm working on.

[skliper]

@jphickey I was actually just starting to look at #346...

[davearch]

Success! It built and now I can run tests! Awesome. Didn't even think of the CFE I suppose I should read up on that documentation too.

[skliper]

See #403 for the CI build implementation.

[skliper]

@davearch see also #404

[skliper]

From #611: I found in section 2.1.1, Setup the OSAL Source Distribution, that the OSAL source distribution directories are not aligned with our current directories. For example, osal/src/make and osal/src/inc no longer exists.

[skliper]

See also #679

[jphickey]

Note that my recent PR #978 addresses many (but not all!) of the items in here.

In particular I left most of the sections regarding the example apps (e.g. "tasking example") alone. Unfortunately tasking example has gone a bit stale and does not directly work out of the box anymore, but we might fix it and bring this back, so I didn't want to remove references to it just yet.

[skliper]

This issue is fixed by #978 and #812. Note #672 is open to address the examples and includes updating the guide.