Skip to content

Special Topics

Nested C++ code

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 compiler creates one .hpp file per package, and one .cpp file per source.

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

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 .bi file:

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

This is useful for executing arbitrary C++ code. It is beyond the scope of this document to detail all the ways in which such code may interface with C++ code generated by the Birch compiler. The following rules cover common use cases, however:

  • Variables declared in Birch code may be used by appending _ to their declared name. Likewise functions and types, where it may also be necessary to prepend the name with a bi:: or bi::type:: namespace designator.
  • Variables of class type declared in Birch code are accessed via custom smart pointers C++ code.
  • Nesting C++ code within fibers requires special care. Variables declared in nested C++ code will not be preserved between yields. One option is to wrap these as member variables within a Birch object, as the object is preserved between yields.

For examples of nested C++ code, see the Birch standard library. For an in-depth study, see the C++ code generated by the Birch compiler in the build/ subdirectory of your Birch project, the libbirch/ subdirectory within the Birch standard library sources, and the C++ code generator within the bi/io/ subdirectory of the Birch compiler sources.