CxxWrap.jl

What is CxxWrap?

• Package for using C++ libraries in Julia
• Library-based approach

Workshop objectives

1. What does it take to enable

   add MyGreatCppPackage

2. How do you wrap:
   • Functions
   • Classes
   • Parametric (template) types
   • Smart pointers
   • STL containers
   • Enum types
   • ...

Project outline

1. JLL package: depends on libcxxwrap-julia
2. Julia package: uses the JLL package and CxxWrap

Building the JLL package

1. Build a library that links to libcxxwrap-julia
• Write CMakeLists.txt
• Write wrapping function
2. Generate the JLL using BinaryBuilder:

   julia --color=yes libfoo/build_tarballs.jl --debug --verbose x86_64-linux-gnu
   julia --color=yes build_tarballs.jl --verbose --meta-json x86_64-linux-gnu > foo.json
   julia build_jll.jl foo.json

3. Set up override for local development
4. Test
5. (publish the JLL)

Building the Julia package

1. Generate a normal Julia package
2. Add CxxWrap and JLL as dependencies
3. Load the library
4. Extend from the Julia side as needed

Workflow conclusions

• Good integration with BinaryBuilder workflow
  • Could use better "local jll" support
  • Julia JLL is not complete yet
• Docker devcontainer + vscode is fairly painless
• Fully native setup is possible too
  • Use distro or Julia or build from source
  • Build libcxxwrap from source and set override file

What is Eigen?

• C++ Matrix library, focused on small matrices
• Uses many tricky C++ features
• There is a JLL already!
• Documentation: http://eigen.tuxfamily.org/dox/GettingStarted.html

Setting up

1. Directory with a .devcontainer with these files.
2. Copy over CMakeLists.txt and foo.cpp as templates.
3. Open in vscode and edit the names

Adding a type

#include <jlcxx/jlcxx.hpp>
#include <jlcxx/stl.hpp>

#include <Eigen/Dense>


JLCXX_MODULE define_julia_module(jlcxx::Module& mod)
{
  mod.add_type<Eigen::MatrixXd>("MatrixXd");
}

module Eigen

using CxxWrap

@wrapmodule "/workspaces/eigen-wrapper/build/lib/libjleigen"

function __init__()
  @initcxx
end

export MatrixXd

end # module

Adding some methods

.method("cols", &Eigen::MatrixXd::cols)
.method("rows", &Eigen::MatrixXd::rows)
.method("norm", &Eigen::MatrixXd::norm)

Adding a constructor

.constructor<int64_t, int64_t>()

Let's add another one

// fails
.method("setConstant", &Eigen::MatrixXd::setConstant);

// Cast
.method("setConstant", static_cast<Eigen::MatrixXd& (Eigen::MatrixXd::*)(const double&)>(&Eigen::MatrixXd::setConstant));

// Or use a lambda
.method("setConstant", [](Eigen::MatrixXd& m, double x) { return m.setConstant(x); });

Adding methods to Base from C++

mod.set_override_module(jl_base_module);
mod.method("getindex", [](const Eigen::MatrixXd& m, int_t i, int_t j) { return m(i-1,j-1); });
mod.method("setindex!", [](Eigen::MatrixXd& m, double value, int_t i, int_t j) { m(i-1,j-1) = value; });
mod.unset_override_module();

mod.method("toString", [] (const Eigen::MatrixXd& m)
{
  std::stringstream stream;
  stream << m;
  return stream.str();
});

Setting a base type

mod.add_type<Eigen::MatrixXd>("MatrixXd", jlcxx::julia_type("AbstractMatrixXd"))

const AbstractMatrixXd = AbstractMatrix{Float64}

# Complete the interface
Base.size(m::MatrixXd) = (rows(m),cols(m))
Base.IndexStyle(::Type{<:MatrixXd})=IndexCartesian()

Templates

namespace jleigen
{
  struct WrapMatrix
  {
    template<typename TypeWrapperT>
    void operator()(TypeWrapperT&& wrapped)
    {
      using WrappedT = typename TypeWrapperT::type;
      using ScalarT = typename WrappedT::Scalar;
      wrapped.template constructor<Eigen::Index, Eigen::Index>();
      wrapped.method("cols", &WrappedT::cols);
      wrapped.method("rows", &WrappedT::rows);
      wrapped.method("norm", &WrappedT::norm);
      wrapped.method("setConstant", static_cast<WrappedT& (WrappedT::*)(const ScalarT&)>(&WrappedT::setConstant));
 
      wrapped.module().set_override_module(jl_base_module);
      wrapped.module().method("getindex", [](const WrappedT& m, int_t i, int_t j) { return m(i-1,j-1); });
      wrapped.module().method("setindex!", [](WrappedT& m, ScalarT value, int_t i, int_t j) { m(i-1,j-1) = value; });
      wrapped.module().unset_override_module();
 
      wrapped.module().method("toString", [] (const WrappedT& m)
      {
        std::stringstream stream;
        stream << m;
        return stream.str();
      });
    }
  };
}
 
namespace jlcxx
{
 
template<typename T>
struct BuildParameterList<Eigen::Matrix<T, Eigen::Dynamic, Eigen::Dynamic>>
{
  typedef ParameterList<T> type;
};
 
}
 
 
JLCXX_MODULE define_julia_module(jlcxx::Module& mod)
{
  using jlcxx::Parametric;
  using jlcxx::TypeVar;
  mod.add_type<Parametric<TypeVar<1>>>("Matrix", jlcxx::julia_type("AbstractMatrix"))
    .apply<Eigen::Matrix<double, Eigen::Dynamic, Eigen::Dynamic>, Eigen::Matrix<float, Eigen::Dynamic, Eigen::Dynamic>>(jleigen::WrapMatrix());
}

Enum types and constants

mod.set_const("Dynamic", int_t(Eigen::Dynamic));

mod.add_bits<Eigen::StorageOptions>("StorageOptions", jlcxx::julia_type("CppEnum"));
mod.set_const("ColMajor", Eigen::ColMajor);
mod.set_const("RowMajor", Eigen::RowMajor);

Templates, completed

struct ApplyMatrix
{
  template<typename T, typename Rows, typename Cols, typename Storage> using apply = Eigen::Matrix<T, Rows::value, Cols::value, Storage::value>;
};

template<typename T, int NRows, int NCols, int S>
  struct BuildParameterList<Eigen::Matrix<T, NRows, NCols, S>>
  {
    using type = ParameterList<T, std::integral_constant<int_t, NRows>, std::integral_constant<int_t, NCols>, std::integral_constant<Eigen::StorageOptions, Eigen::StorageOptions(S)>>;
  };
  
  }
  
  
  JLCXX_MODULE define_julia_module(jlcxx::Module& mod)
  {
    mod.set_const("Dynamic", int_t(Eigen::Dynamic));
    
    mod.add_bits<Eigen::StorageOptions>("StorageOptions", jlcxx::julia_type("CppEnum"));
    mod.set_const("ColMajor", Eigen::ColMajor);
    mod.set_const("RowMajor", Eigen::RowMajor);
  
    using jlcxx::Parametric;
    using jlcxx::TypeVar;
    using jlcxx::ParameterList;
  
    using scalar_types = ParameterList<float, double>;
    using sizes = ParameterList<std::integral_constant<int, 2>, std::integral_constant<int, 4>, std::integral_constant<int, Eigen::Dynamic>>;
    using storage = ParameterList<std::integral_constant<int, Eigen::ColMajor>, std::integral_constant<int, Eigen::RowMajor>>;
  
    mod.add_type<Parametric<TypeVar<1>, TypeVar<2>, TypeVar<3>, TypeVar<4>>>("Matrix", jlcxx::julia_type("AbstractEigenMatrix"))
      .apply_combination<jleigen::ApplyMatrix, scalar_types, sizes, sizes, storage>(jleigen::WrapMatrix());
  }

Inheritance

class ExtendedMatrix : public Eigen::Matrix<double,4,4>
  {
  public:
      using base_t = Eigen::Matrix<double,4,4>;
      ExtendedMatrix() : base_t() { setConstant(1.0); }
  
      // This constructor allows you to construct ExtendedMatrix from Eigen expressions
      template<typename OtherDerived>
      ExtendedMatrix(const Eigen::MatrixBase<OtherDerived>& other)
          : base_t(other)
      { }
  
      // This method allows you to assign Eigen expressions to ExtendedMatrix
      template<typename OtherDerived>
      ExtendedMatrix& operator=(const Eigen::MatrixBase <OtherDerived>& other)
      {
          this->base_t::operator=(other);
          return *this;
      }
  };

namespace jlcxx
{

template<> struct SuperType<jleigen::ExtendedMatrix> { using type = Eigen::Matrix<double,4,4>; };

}

mod.add_type<jleigen::ExtendedMatrix>("ExtendedMatrix", jlcxx::julia_base_type<Eigen::Matrix<double,4,4>>());

Smart pointers

#include <jlcxx/smart_pointers.hpp>
mod.method("make_shared", [] ()
{
  return std::make_shared<Eigen::MatrixXd>(3,3);
});

Standard vector

mod.method("processvec", [] (const std::vector<Eigen::MatrixXd>& v)
{
  for(auto val : v)
  {
    std::cout << val << std::endl;
  }
});