-
Notifications
You must be signed in to change notification settings - Fork 14
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.