jluna: A Julia Wrapper for C++#

Welcome to the documentation for jluna, a Julia-wrapper for C++.

It allows for easy integration of Julia scripts and packages into projects with C++ as the host language, making language interaction easy and convenient.

It is available under MIT License, on GitHub.

This documentation includes a step-by-step guide on how to install jluna, a manual and tutorial introducing all of jlunas features, as well as an index of all of jlunas function, intended to be easily referenced back to during development.

jluna was designed and implemented by C. Cords.


Note

For all chapters, an interactive list of sections is provided in the top right corner of the page.

Table of Contents#

Please navigate to the appropriate section below:


FAQ: What is the difference between jluna and …?#

With C++ being as widely used as it is, confusion may arise as to what purpose jluna serves when compared to a number of other C++-interfacing Julia packages. These will be addressed in this section.

Julia C-API#

The Julia C-API provides the “backbone” of Julia and is the basis for jluna and most other foreign-language libraries interacting with Julia. While powerful, the C-API can be quite hard to use and poorly documented. jluna aims to resolve this, fully wrapping the C-API in all of the convenience of modern C++: automatic memory management, proper exception handling and much nicer syntax. Other than this, Julia C-API and jluna are functionally equivalent.

The one area where jluna actually has more features than the C-API is in parallelization: jluna provides a thread pool that allows C-side functions to interact with the Julia state, something that is not possible using only he C-API.

Cxx.jl#

Cxx.jl aims to provide users with a way to run C++ code natively from within Julia, using the @cxx macro. Unlike jluna, Cxx.jl assumes Julia as the host language, while jluna assumes C++. Furthermore, the Cxx.jl is currently unmaintained, only supporting Julia versions older than 1.3. jluna specifically requires 1.7 or newer.

CxxWrap.jl#

CxxWrap.jl is related to Cxx.jl, in that both assume Julia as the host language and both allow for direct access of C++ functionality from within Julia. It allows to compile C++ code into a shared library that can then be used directly from within Julia. This is very similar to jluna, with two major difference: Firstly, jluna is a Julia-wrapper for C++, while CxxWrap is a C++-wrapper for Julia. While, in concept, both overlap, the decision on which to use should be based on what host language a specific project has. If Julia is the “main” language that interacts with all parts of a project, CxxWrap.jl may be a better fit than jluna, if C++ takes that place, jluna may be superior.

In addition, CxxWrap.jl and jluna have no architectural design in common, jluna was created completely independently and does not mimic any of CxxWrap.jl features directly, and vice-versa. Whether this is advantageous or disadvantageous depends on the individual user and application.

Lastly, a much more minor difference is that jluna was designed from the ground up using C++20 techniques such as concepts, making it’s C++ code much more modern. In exchange for the nicer syntax and future-proofing, jluna requires up-to-date compilers.

CxxInterface.jl / CxxCall.jl#

CxxInterface.jl and CxxCall.jl both aim to call C++ functions (contained in a shared library) from Julia. They essentially are a ccall for C++, not a full language wrapper, the projects are therefore not functionally equivalent. jluna does provide a way for the julia state to call any C++ function, the mechanism to achieve this is completely different, however.


In summary, the only fully functional equivalent for jluna is the Julia C-API, as only it provides a Julia-wrapper that assumes C / C++ as the host language. It is therefore the superior choice in projects where Julia plays an auxiliary rule while C++ is more dominant, as jluna provides clearer design, more documentation and overall ease-of-use when compared to the C-API.


FAQ: Is it done / fast yet?#

Julia is feature-complete as of 0.9.0. This release also included extensive benchmarking, quantifying jlunas performance and proving its capability for excellent performance. Correctness is assured through automated testing.

0.9.x will be upgraded to 1.0 in winter 2022, even if no new features are implemented. This is to give the community time to make possible suggestions / corrections.