npm 中文文档

C++ Language Interface Foundation (CLIF)


CI

PyCLIF defines a C++ API to be wrapped via a concise What You See Is What You Getinterface file (example ), with a syntax derived from pytypedecl.

About the name of this repo: CLIF was started as a common foundation for creating C++ wrapper generators for various languages. However, currently Python is the only target language, and there is no development activity for other target languages.

Overview


PyCLIF consists of four parts:

Parser
Matcher
Generator
Runtime

Parser


The parser converts a language-friendly C++ API description to the language-agnostic internal format and passes it to the Matcher.

Matcher


The matcher parses selected C++ headers with Clang (LLVM's C++ compiler) and collects type information.  That info is passed to the Generator.

Generator


The generator emits C++ source code for the wrapper.

The generated wrapper needs to be built according with language extension rules. Usually that wrapper will call into the Runtime.

Runtime


The runtime C++ library holds type conversion routines that are specific to each target language but are the same for every generated wrapper.

Python CLIF


See complete implementation of a Python wrapper generator in the /python/ subdirectory.  Both Python 2 and 3 are supported.

Installation


Prerequisites


We use CMake, so make sure CMake version 3.5 or later is available. (For example, Debian 8 only has version 3.0, so in that case you'll need to install an up-to-date CMake.)

We use Google protobuf for inter-process communication between the CLIF frontend and backend. Version 3.8.0 or later is required. Please install protobuf for both C++ and Python from source, as we will need some protobuf source code later on.

You must have virtualenv installed.

You must have pyparsing installed, so we can build protobuf. Use pip install 'pyparsing==2.2.0' to fetch the correct version.

Make sure pkg-config --libs python works (e.g. install python-dev and pkg-config ).

We use Clang (LLVM's C++ compiler) to parse C++ headers, so make sure Clang and LLVM version 11 is available. On Ubuntu and Debian, you can install the prebuilt version from https://apt.llvm.org.

You must have abseil-cpp installed.

We use googletest for unit testing C++ libraries.

For references, there is a Dockerfile running an Ubuntu image with all the prerequisites already installed. See the instructions at the top of the file.

Building


To build and install CLIF to a virtualenv, run:

  1. ``` shell
  2. virtualenv --python=python3.x clif-venv
  3. ./INSTALL.sh clif-venv/bin/python
  4. ```

The following outlines the steps in INSTALL.sh for clarification.

Build and install the CLIF backend. If you use Ninja instead of make your build will go significantly faster. It is used by Chromium, LLVM et al. Look at INSTALL.sh for the directory setup and proper ...flags... to supply the cmake command here:

  1. ``` shell
  2. mkdir build
  3. cd build
  4. cmake ...flags... $CLIFSRC_DIR
  5. make clif-matcher
  6. make install
  7. ```

Replace the cmake and make commands with these to use Ninja:

  1. ``` shell
  2. cmake -G Ninja ...flags... $CLIFSRC_DIR
  3. ninja clif-matcher
  4. ninja -j 2 install
  5. ```

If you have more than one Python version installed (eg. python3.6 and python3.7) cmake may have problems finding python libraries for the Python you specified as INSTALL.sh argument and uses the default Python instead. To help cmake use the correct Python add the following options to the cmake command (substitute the correct path for your system):

  1. ``` shell
  2. cmake ... \
  3.   -DPYTHON_INCLUDE_DIR="/usr/include/python3.6" \
  4.   -DPYTHON_LIBRARY="/usr/lib/x86_64-linux-gnu/libpython3.6m.so" \
  5.   -DPYTHON_EXECUTABLE="/usr/bin/python3.6" \
  6.   "${CMAKE_G_FLAGS[@]}" "$CLIFSRC_DIR"
  7. ```

Get back to your CLIF python checkout and install it using pip.

  1. ``` shell
  2. cd "$CLIFSRC_DIR"
  3. cp "$BUILD_DIR/clif/protos/ast_pb2.py" clif/protos/
  4. cp "$BUILD_DIR/clif/python/utils/proto_util.cc" clif/python/utils/
  5. cp "$BUILD_DIR/clif/python/utils/proto_util_clif.h" clif/python/utils/
  6. cp "$BUILD_DIR/clif/python/utils/proto_util.init.cc" clif/python/utils/
  7. pip install .
  8. ```

That version is guaranteed to work. Older versions likely do not work (they lack some APIs); later versions might work, at your own risk.

INSTALL.sh will build and install clif-matcher to CMake install directory and CLIF for Python to the given Python (virtual) environment.

To run Python CLIF use pyclif.

Using your newly built pyclif


First, try some examples:

  1. ``` shell
  2. cd examples
  3. less README.md
  4. ```

Next, read the Python CLIF User Manual.

For more details please refer to:

CLIF Python Primer
CLIF FAQ

Disclaimer


This is not an official Google product.