In addition to header files used for system libraries locally developed
libaries exist. Such libraries may very well have traditionally been
developed, using standard header files. But once project start using modules
it might be attractive to convert the traditional header files to
module-compiled header files. 

To module-compile a standard header file (e.g., an existing tt(support.h)
header file in a tt(support) sub-directory) to a module-compiled header file
issue the command
 verb(    g++ --std=c++26 -Wall -fmodules-ts -x c++-header support.h)
    The compiler then writes the module-compiled header file tt(support.h.gcm)
in the tt(./gcm.cache/,/) sub-directory (note: in tt(gcm.cache's) `comma'
sub-directory).  

When a library is constructed there are usually multiple header files, between
which some hierarchy may exist. Consider a library consisting of three
classes: tt(Top), depending on tt(Middle), which in turn depends on tt(Base)
Each class is defined in its own sub-directory. E.g., tt(base/base.h):
    verbinsert(-as4 examples/locallib/base/base.h)

    tt(middle/middle.h):
    verbinsert(-as4 examples/locallib/middle/middle.h)

    and tt(top/top.h):
    verbinsert(-as4 examples/locallib/top/top.h)

To module-compile the library's headers the tt(gcm.cache) organization as
described in section ref(MODINIT) is used (a tt(gcm.cache) directory is
defined at the project's top-level directory, while sub-directories define
tt(gcm.cache) soft-links to the top-level tt(gcm.cache) directory). Next each
header file is module-compiled whereafter the tt(gcm.cache) subdirectory
contains: 
 verb(
    ,/base.h.gcm
    ,/middle.h.gcm
    ,/top.h.gcm
    usr -> /usr
 )

This, however, is not the organization which is expected by programs that need
to use the module-compiled headers. To compare: the module-compiled system
header files are, together with the system header files themselves, located in
tt(/usr/include/c++/14) (like tt(iostream) and tt(iostream.gcm)). When 
module-compiled headers should be used by programs a similar organization is
expected. But that's easily realized by defining a sub-directory (e.g.,
tt(hdrs)) containing soft-links to each of the library's header files and
to each of the library's module-compiled header files. If tt(hdrs) is a
sub-directory of the libraary's top-level directory then it contains
 verb(
    base.h       -> ../base/base.h
    base.h.gcm   -> ../gcm.cache/,/base.h.gcm
    middle.h     -> ../middle/middle.h
    middle.h.gcm -> ../gcm.cache/,/middle.h.gcm
    top.h        -> ../top/top.h
    top.h.gcm    -> ../gcm.cache/,/top.h.gcm
 )

As elaborated in the following two sub-sections there are two ways programs
using the local library can import the library's module-compiled headers: by
using a relative path to the tt(hdrs) sub-directory or by using an absolute
path to the tt(hdrs) subdirectory.


COMMENT( OBS

============================================



 a program using tt(support.h) (like
tt(main.cc) in the project's top-level directory) can now do either
tt(#include "support/support.h")


If the header
file and its 
module-compiled version are available in, respectively, the current directory
and the tt(gcm.cache/,/) sub-directory then the header can be imported. E.g,
if tt(support.ih) is
    verbinsert(-as4 examples/localhdr/support.h)
    then tt(main.cc) can import it:
    verbinsert(-as4 examples/localhdr/main.cc)

But this doesn't work if tt(support.h) isn't defined in tt(main.cc's)
directory but in, e.g., a tt(support/) sub-directory, with tt(main.cc) using
the import statement tt(import "support/support.h"). Now, when tt(main.cc) is
compiled the compiler reports:
 verb(    In module imported at main.cc:1:1:
    ./support/support.h: note: compiled module file is 
                                        ‘gcm.cache/,/support/support.h.gcm’
 )
    Although this issue can be solved by defining a soft-link
 verb(    ../../gcm.cache/,/support/ -> support/gcm.cache/,/)
    it also opens a can of worms: multiple headers probably exist, each in
its own directory, and making each header file and its module-compiled file,
living in its own tt(gcm.cache/,/) sub-directory, available to each of the
project's source files quickly turns into a Herculean task. 

Fortunately, when preparing an existing local library for being used by
modules, a simpler alternative exists. The library itself can remain as-is, but
its header files can be module-compiled and made available (like 
module-compiled system header files) in one local sub-directory.



- in ./localhdr zijn de headers en headers.gcm files
- in ./gcm.cache/,/ is een link naar comphdrs
- compile met -i system comphdrs source.cc om de (mod-comp) headers in
  gcm.cache te bereiken. 


First some preparatory steps are performed (only once):
    itemization(
    it() assume the local library tt(MyLib) is developed below the
        sub-directory tt(~/mylib). tt(MyLib) has multiple sub-directories,
        each of which defines a header file declaring the component (e.g.,
        class) defined in its sub-directory, like tt(classa) (defining module
        tt(ClassA)), tt(classb) (defining module tt(ClassB)), ...;
    it() To make the header files available to other projects, a sub-directory
        tt(~/include/mylib) is defined, and each header file of the tt(MyLib)
        library can be reached via a soft-link from tt(~/include/mylib). E.g.,
        tt(~/include/mylib/classa -> ~/mylib/classa/classa).
    )

Next, if a module-aware project must import module-aware variants of (some of)
tt(MyLib's) header files, 
    itemization(
    it() those module-aware variants can, since the library's header files are
        available in tt(~/include/mylib), be constructed in that directory;
    it() then, when compiling the project's source files, add the flag 
        tt(-isystem ~/include/mylib) to the compiler flags. E.g., to compile a
        project's tt(main.cc) file use
  verb(    g++ -c --std=c++26 -fmodules-ts -isystem ~/include/mylib main.cc)
    it() Source files can now import the library's module-aware header files
        using, e.g., tt(import <classa>;) 
    )
    
When the local library was designed merely using modules, then a similar
procedure can be used as described in the previous section for system
libraries.

COMMENT(examples/libmodhdr, examples/mylib)

END OBS)
