Document the CMake interface

[dibyendumajumdar]

It seems to me that the build requires that front-end projects make use of certain CMake functions defined in OmrCompilerSupport.cmake.

For instance - create_omr_compiler_library() - creates the library / but also includes all the Compiler sources. It also appears to ensure that the projects include path is prioritized over the Compiler ones.

Client front-end projects must use these functions I believe?

[fjeremic]

Paging our CMake expert @dnakamura for this one. Are you able to help answer the above question?

[dnakamura]

Strictly speaking you don't actually need to use those functions, but they do make life much easier. If I'm being honest I didnt write those functions and only have a sorta vauge understanding of how they work. Ideally I would like to see them repackaged as interface libraries that you can just link against, and have cmake do all the heavy lifting.

As I understand it the functions do a couple things:

• Add in source files from the base omr compiler component. As part of this you can have it exclude certain sources (although I'm not sure we actually use this capability)
• Include path management. This is to support the weird sorta reverse inheritance scheme in the compiler, which relies on strict ordering of the include paths and headers with the same name. (For this I only understand the "how", @fjeremic can explain the "why")
• Pre-process assembly files. This is platform specific. (for example when compiling on windows we convert the sources from AT&T syntax to Intel)
• Creates a version file (basically just a c file which defines some version/name strings)

[fjeremic]

Include path management. This is to support the weird sorta reverse inheritance scheme in the compiler, which relies on strict ordering of the include paths and headers with the same name. (For this I only understand the "how", @fjeremic can explain the "why")

You can read all about the "why" portion of the answer in great detail here:
https://github.com/eclipse/omr/tree/7b106b8034230e0de988c520cb2b3c0ce7e908b3/doc/compiler/extensible_classes

At a 10k foot level we try to save compile time by avoiding virtual inheritance in the JIT.

There will also be a discussion on this and a new proposal in the next OMR Architecture Meeting (#2571). If you're interested in the area you can try to attend or view a recording of the discussion.