Nesting raw C plus plus code in Birch

The Birch language permits raw C++ code to be nested. Nesting C++ code requires some understanding of how the Birch compiler translates Birch code to C++ code, and this translation is still in flux.

The primary motivation for nested C++ is to wrap Birch language interfaces around existing C++ language libraries. The Birch standard library, for example, uses this feature to integrate parts of the C++ Standard Template Library and Eigen linear algebra library. The use of nested C++ code for other purposes is discouraged, and it is recommended that its use is kept to a minimum, with any lengthy or complex nested C++ code separated into dedicated header and source files.

When building a package, the Birch driver creates one .hpp file per package, and multiple .cpp files according to the --unit command-line option.

To include raw C++ code in the .hpp file, use the following, typically at the root scope of a .birch file or within a class:

hpp{{
// C++ code here
}}

This is useful for #include directives, or for declaring C++ types and functions.

To include raw C++ code in the .cpp file, use the following, typically in the body of a function in a .birch file:

cpp{{
// C++ code here
}}

This is useful for executing arbitrary C++ code. Variables declared in Birch code may be used as-named in C++ code. Functions may be used by prefacing their name with the namespace birch::, and types with the namespace birch::type.

When using birch build, you may like to add --disable-translate to prevent C++ error messages being translated to Birch error messages, in order that you can see the original output from the C++ compiler for errors related to your nested C++ code.

For good examples of using nested C++ code to wrap C/C++ library functionality, see the SQLite, Cairo, and parts of the standard library. For an in-depth study, see the C++ code generated by the Birch compiler itself, and the LibBirch C++ Library, which supports the C++ code generated by the Birch compiler.