The cxx Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cxx Reference Manual

This is the cxx Reference Manual, version 1.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 14:40:02 2021 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Update: CL-CXX-JIT is the new project to make the process easier example: (from '("<cmath>") 'import '("static_cast<double(*)(double)>(std::sin)" . "cpp-sin")), then can be called with(cpp-sin 0d0).

CL-CXX - Common Lisp wrappers for C++

This library provides an interface to C++ from lisp. It was inspired by Julia's libcxxwrap, and that projects documentation is a good reference for the architecture and ideas in this library.

Prerequisites

Installation

Clone into home/common-lisp directory. Then asdf:test-system "cxx"

Supported Types

A Small Example

First you will need to create a C++ glue library that CFF will use when calling C++ functions from Lisp. Compile the code below as a shared library say, libtest.so or libtest.dylib. The commands to do this will vary by compiler and operating system. For testing, it is always good to put the library in the same directory as the lisp code, and ensure that you set the current working directory in your Lisp image. CFFI can take some fiddling to find all the dependencies. This is not unique to this project, all Lisp C/C++ bindings with CFFI have the same requirements.

The C++ Side of the Equation

#include <string>
#include "clcxx/clcxx.hpp"

std::string greet() { return "Hello, World"; }
int Int(int x) { return x + 100; }
float Float(float y) { return y + 100.34; }
auto gr(std::complex<float> x) { return x; }
std::string hi(char* s) { return std::string("hi, " + std::string(s)); }
void ref_int(int& x) { x += 30; }
void ref_class(xx& x) { x.y = 1000000; }
class xx {
 public:
  xx(int xx, int yy) : y(yy), x(xx) {}
  std::string greet() { return "Hello, World"; }
  int y;
  int x;
};

CLCXX_PACKAGE TEST(clcxx::Package& pack) {
  pack.defun("hi", &hi);
  pack.defun("test-int", &Int);
  pack.defun("greet", &greet);
  pack.defun("test-float", &Float);
  pack.defun("test-complex", &gr);
  pack.defun("ref-int", &ref_int);
  pack.defun("ref-class", &ref_class);
  pack.defclass<xx, false>("xx")
      .member("y", &xx::y)
      .defmethod("foo", &xx::greet)
      .constructor<int, int>();
}

The Lisp Side of Things

You should walk through the commands below in the REPL to get an idea of how the bindings work. Before you start, ensure you have the dependencies loaded:

(ql:quickload "cffi")
(ql:quickload "cxx")
(defpackage cxx/test
  (:use :cl))
(in-package :cxx/test)

;;; Change the pathname to match that of your system.
(pushnew (merge-pathnames #p"ros/lisp-demo/lib/" (user-homedir-pathname))
         cffi:*foreign-library-directories*
         :test #'equal)

(cffi:define-foreign-library my-lib
  (t (:default "libtest")))

(cffi:use-foreign-library my-lib)

(cxx:init)

(cxx:add-package "TEST" "TEST")

(test:greet)

(test:hi "Cxx")

Usage

See test files or the cl-cxx-eigen project for further examples.

NOTE

Tested on:

TODO

Copyright

Copyright (c) 2018 Islam Omar (io1131@fayoum.edu.eg)

License

Licensed under the MIT License.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cxx

Author

Islam Omar

License

MIT

Description

Common Lisp Cxx Interoperation

Long Description

# Update: [CL-CXX-JIT](https://github.com/Islam0mar/CL-CXX-JIT) is the new project to make the process easier example: ‘(from ’("<cmath>") ’import ’("static_cast<double(*)(double)>(std::sin)" . "cpp-sin")),‘ then can be called with‘(cpp-sin 0d0)‘.
# CL-CXX - Common Lisp wrappers for C++

This library provides an interface to C++ from lisp. It was inspired by Julia’s [libcxxwrap](https://github.com/JuliaInterop/libcxxwrap-julia), and that projects documentation is a good reference for the architecture and ideas in this library.

## Prerequisites

- [CLCXX](https://github.com/Islam0mar/CLCXX) is installed

## Installation

Clone into home/common-lisp directory. Then ‘asdf:test-system "cxx"‘

## Supported Types

* Fundamental types
* Pointers
* Classes can add public members and functions
* POD
* functions, std::function and lambda

## A Small Example
First you will need to create a C++ glue library that CFF will use when calling C++ functions from Lisp. Compile the code below as a shared library say, libtest.so or libtest.dylib. The commands to do this will vary by compiler and operating system. For testing, it is always good to put the library in the same directory as the lisp code, and ensure that you set the current working directory in your Lisp image. CFFI can take some fiddling to find all the dependencies. This is not unique to this project, all Lisp C/C++ bindings with CFFI have the same requirements.

### The C++ Side of the Equation
“‘c++
#include <string>
#include "clcxx/clcxx.hpp"

std::string greet() { return "Hello, World"; }
int Int(int x) { return x + 100; }
float Float(float y) { return y + 100.34; }
auto gr(std::complex<float> x) { return x; }
std::string hi(char* s) { return std::string("hi, " + std::string(s)); }
void ref_int(int& x) { x += 30; }
void ref_class(xx& x) { x.y = 1000000; }
class xx {
public:
xx(int xx, int yy) : y(yy), x(xx) {}
std::string greet() { return "Hello, World"; }
int y;
int x;
};

CLCXX_PACKAGE TEST(clcxx::Package& pack) {
pack.defun("hi", &hi);
pack.defun("test-int", &Int);
pack.defun("greet", &greet);
pack.defun("test-float", &Float);
pack.defun("test-complex", &gr);
pack.defun("ref-int", &ref_int);
pack.defun("ref-class", &ref_class);
pack.defclass<xx, false>("xx")
.member("y", &xx::y)
.defmethod("foo", &xx::greet)
.constructor<int, int>();
}
“‘

### The Lisp Side of Things
You should walk through the commands below in the REPL to get an idea of how the bindings work. Before you start, ensure you have the dependencies loaded:

“‘common lisp
(ql:quickload "cffi")
(ql:quickload "cxx")
“‘

“‘common lisp
(defpackage cxx/test
(:use :cl))
(in-package :cxx/test)

;;; Change the pathname to match that of your system.
(pushnew (merge-pathnames #p"ros/lisp-demo/lib/" (user-homedir-pathname))
cffi:*foreign-library-directories*
:test #’equal)

(cffi:define-foreign-library my-lib
(t (:default "libtest")))

(cffi:use-foreign-library my-lib)

(cxx:init)

(cxx:add-package "TEST" "TEST")

(test:greet)

(test:hi "Cxx")
“‘

## Usage

See test files or the [cl-cxx-eigen](https://github.com/Islam0mar/cl-cxx-eigen) project for further examples.

### NOTE

Tested on:
* SBCL 1.4.5 on debian
* CCL 1.12 on MacOS 10.13.6

## TODO

- [x] test functions
- [x] classes
- [x] references
- [ ] Smart pointers
- [ ] Tuple
- [ ] benchmark

## Copyright

Copyright (c) 2018 Islam Omar (io1131@fayoum.edu.eg)

## License

Licensed under the MIT License.

Version

1.0

Dependencies
Source

cxx.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 cxx/src

Parent

cxx (system)

Location

src/

Components

Next: , Previous: , Up: Top   [Contents][Index]

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 cxx.asd

Location

cxx.asd

Systems

cxx (system)

Packages

cxx/system


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 cxx/package.lisp

Parent

cxx (system)

Location

package.lisp

Packages

cxx


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.3 cxx/src/utilities.lisp

Parent

src (module)

Location

src/utilities.lisp

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.4 cxx/src/c-types.lisp

Parent

src (module)

Location

src/c-types.lisp

Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

4.1.5 cxx/src/cxx.lisp

Parent

src (module)

Location

src/cxx.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

5.1 cxx/system

Source

cxx.asd

Use List

Previous: , Up: Packages   [Contents][Index]

5.2 cxx

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Functions

Function: add-package PACK-NAME FUNC-NAME

Register lisp package with pack-name from func-name defined in CXX lib

Package

cxx

Source

cxx.lisp (file)

Function: init ()
Package

cxx

Source

cxx.lisp (file)

Function: remove-package PACK-NAME
Package

cxx

Source

cxx.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Functions

Function: cffi-type TYPE

Returns cffi-type as a keyword or list of keywords

Package

cxx

Source

cxx.lisp (file)

Function: clcxx-init ERR-CALLBACK REG-DATA-CALLBACK
Package

cxx

Source

cxx.lisp (file)

Function: compound-type-list TYPE &optional ARRAY-P

Returns a list of strings representing compound type

Package

cxx

Source

cxx.lisp (file)

Function: get-parenthes-string STRING

Returns a string within first (...) or nil

Package

cxx

Source

utilities.lisp (file)

Function: left-trim-string-to STRING CHAR

Returns a string trimmed to char exclusive

Package

cxx

Source

utilities.lisp (file)

Function: parse-args ARG-TYPES &optional INPUT-TYPE-P

return argument types (with variables if they are inputs) in a proper list

Package

cxx

Source

cxx.lisp (file)

Function: parse-class META-PTR

Define class

Package

cxx

Source

cxx.lisp (file)

Function: parse-class-slots SLOT-NAMES SLOT-TYPES

Returns super class as symbols in a list

Package

cxx

Source

cxx.lisp (file)

Function: parse-constant META-PTR

Define constant

Package

cxx

Source

cxx.lisp (file)

Function: parse-function META-PTR

Retruns the function def.

Package

cxx

Source

cxx.lisp (file)

Function: parse-super-classes S

Returns super class as symbols in a list

Package

cxx

Source

cxx.lisp (file)

Function: parse-type TYPE

Returns cffi-type as a keyword or list of keywords

Package

cxx

Source

cxx.lisp (file)

Function: register-package NAME PACK-PTR
Package

cxx

Source

cxx.lisp (file)

Function: remove-c-package NAME
Package

cxx

Source

cxx.lisp (file)

Function: remove-string REM-STRING FULL-STRING &key FROM-END TEST TEST-NOT START1 END1 START2 END2 KEY

returns full-string with rem-string removed

Package

cxx

Source

utilities.lisp (file)

Function: required &optional MSG &rest ARGS

If this ever gets called, it means something that was required was not supplied. Use as default value for &key args or defstruct slots.

Package

cxx

Source

utilities.lisp (file)

Function: split-string-by STRING CHAR

Returns a list of substrings of string divided by ONE + each.
;; Note: Two consecutive pluses will be seen as ;; if there were an empty string between them.

Package

cxx

Source

utilities.lisp (file)

Function: symbols-list ARG-TYPES &optional METHOD-P CLASS-OBJ

Return a list of symbols ’(V0 V1 V2 V3 ...) representing the number of args

Package

cxx

Source

cxx.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Classes

Class: class-info-tclass ()
Package

cxx

Source

c-types.lisp (file)

Direct superclasses
  • translatable-foreign-type (class)
  • foreign-struct-type (class)
Class: constant-info-tclass ()
Package

cxx

Source

c-types.lisp (file)

Direct superclasses
  • translatable-foreign-type (class)
  • foreign-struct-type (class)
Class: cxx-complex-tclass ()
Package

cxx

Source

c-types.lisp (file)

Direct superclasses
  • translatable-foreign-type (class)
  • foreign-struct-type (class)
Class: function-info-tclass ()
Package

cxx

Source

c-types.lisp (file)

Direct superclasses
  • translatable-foreign-type (class)
  • foreign-struct-type (class)

Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
cxx.asd: The cxx․asd file
cxx/package.lisp: The cxx/package․lisp file
cxx/src: The cxx/src module
cxx/src/c-types.lisp: The cxx/src/c-types․lisp file
cxx/src/cxx.lisp: The cxx/src/cxx․lisp file
cxx/src/utilities.lisp: The cxx/src/utilities․lisp file

F
File, Lisp, cxx.asd: The cxx․asd file
File, Lisp, cxx/package.lisp: The cxx/package․lisp file
File, Lisp, cxx/src/c-types.lisp: The cxx/src/c-types․lisp file
File, Lisp, cxx/src/cxx.lisp: The cxx/src/cxx․lisp file
File, Lisp, cxx/src/utilities.lisp: The cxx/src/utilities․lisp file

L
Lisp File, cxx.asd: The cxx․asd file
Lisp File, cxx/package.lisp: The cxx/package․lisp file
Lisp File, cxx/src/c-types.lisp: The cxx/src/c-types․lisp file
Lisp File, cxx/src/cxx.lisp: The cxx/src/cxx․lisp file
Lisp File, cxx/src/utilities.lisp: The cxx/src/utilities․lisp file

M
Module, cxx/src: The cxx/src module

Jump to:   C   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   C   F   G   I   L   P   R   S  
Index Entry  Section

A
add-package: Exported functions

C
cffi-type: Internal functions
clcxx-init: Internal functions
compound-type-list: Internal functions

F
Function, add-package: Exported functions
Function, cffi-type: Internal functions
Function, clcxx-init: Internal functions
Function, compound-type-list: Internal functions
Function, get-parenthes-string: Internal functions
Function, init: Exported functions
Function, left-trim-string-to: Internal functions
Function, parse-args: Internal functions
Function, parse-class: Internal functions
Function, parse-class-slots: Internal functions
Function, parse-constant: Internal functions
Function, parse-function: Internal functions
Function, parse-super-classes: Internal functions
Function, parse-type: Internal functions
Function, register-package: Internal functions
Function, remove-c-package: Internal functions
Function, remove-package: Exported functions
Function, remove-string: Internal functions
Function, required: Internal functions
Function, split-string-by: Internal functions
Function, symbols-list: Internal functions

G
get-parenthes-string: Internal functions

I
init: Exported functions

L
left-trim-string-to: Internal functions

P
parse-args: Internal functions
parse-class: Internal functions
parse-class-slots: Internal functions
parse-constant: Internal functions
parse-function: Internal functions
parse-super-classes: Internal functions
parse-type: Internal functions

R
register-package: Internal functions
remove-c-package: Internal functions
remove-package: Exported functions
remove-string: Internal functions
required: Internal functions

S
split-string-by: Internal functions
symbols-list: Internal functions

Jump to:   A   C   F   G   I   L   P   R   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   F   P   S  
Index Entry  Section

C
Class, class-info-tclass: Internal classes
Class, constant-info-tclass: Internal classes
Class, cxx-complex-tclass: Internal classes
Class, function-info-tclass: Internal classes
class-info-tclass: Internal classes
constant-info-tclass: Internal classes
cxx: The cxx system
cxx: The cxx package
cxx-complex-tclass: Internal classes
cxx/system: The cxx/system package

F
function-info-tclass: Internal classes

P
Package, cxx: The cxx package
Package, cxx/system: The cxx/system package

S
System, cxx: The cxx system

Jump to:   C   F   P   S