How to contribute¶

How to build¶

Get the BDTK Source¶

$ git clone --recursive https://github.com/intel/BDTK.git
$ cd BDTK
# if you are updating an existing checkout
$ git submodule sync --recursive
$ git submodule update --init --recursive

Setting up BDTK develop envirenmont on Linux Docker¶

We provide Dockerfile to help developers setup and install BDTK dependencies.

# Build an image from a Dockerfile
$ cd ${path_to_source_of_bdtk}/ci/docker
$ docker build -t ${image_name} .

# Start a docker container for development
docker run -d --name ${container_name} --privileged=true -v ${path_to_bdtk}:/workspace/bdtk ${image_name} /usr/sbin/init

docker exec -it ${container_name} /bin/bash

Build in container¶

Once you have setup the Docker build envirenment for BDTK and get the source, you can enter the BDTK container and build like: Run make in the root directory to compile the sources. For development, use make debug to build a non-optimized debug version, or make release to build an optimized version. Use make test-debug or make test-release to run tests.

How to debug/test¶

How to run all unit tests¶

# WORKDIR: /workspace/bdtk
# test both cider and cider-velox
make test-debug/release

# only test cider
make test-cider BUILD_TYPE=Debug/Release /test-cider-velox

# only test cider-velox
make test-cider-velox BUILD_TYPE=Debug/Release

# Note: If you want to test both Debug and Release, just use '&&' to connect two commands.

How to run a single unit test¶

# For Cider
# Test Path: /workspace/bdtk/build-$BUILD_TYPE/cider/tests
./XXXtest

# For CiderVelox
# Test Path: /workspace/bdtk/build-$BUILD_TYPE/cider-velox/tests

# Please check is there a function directory(auto generate when make test-$BUILD_TYPE) under cider-velox.
# If not, please use follow commands to get one(under /workspace/bdtk/):
#   mkdir /workspace/bdtk/build-${BUILD_TYPE}/cider-velox/function
#   cp /workspace/bdtk/build-${BUILD_TYPE}/cider/function/*.bc /workspace/bdtk/build-{BUILD_TYPE}/cider-velox/function
#   cd /workspace/bdtk/build-${BUILD_TYPE}cider-velox/test
./XXXtest

How to debug a single unit test¶

configure GDB with the built test binaries, like following:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
    {
      "name": "${name_of_this_configuration}",
      "type": "cppdbg",
      "request": "launch",
      "program": "${path_to_the_test_you_want_to_debug}",
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "environment": [],
      "externalConsole": false,
      "MIMode": "gdb",
      "setupCommands": [
          {
              "description": "Enable pretty-printing for gdb",
              "text": "-enable-pretty-printing",
              "ignoreFailures": true
          }
      ]
    }
    ]
}

Code style check¶

Code style check will be triggered automatically after you submit a PR. So please ensure your PR does not break any of these workflows. It runs make format-check, make header-check as part of our continuous integration. Pull requests should pass format-check and header-check without errors before being accepted.

More details can be found at ci/scripts/run_cpplint.py

Documentation¶

BDTK documentation uses sphinx to produce html structure. Github pages refer to “docs” directory on “gh-pages” branch.

Build and commit

We maintain gh-pages with github actions, which is implemented in .github/workflows/update-gh-pages.yml.

We can simply edit rst files under “docs” directory, when the change merge to “main” branch, github action will automatically build gh-pages.

If you want to add a new rst file, remember add its title to “index.rst”.

External links

Last, share some tools and documents, hope it can help:

Sphinx quick start: sphinx-doc
How to write rst(reStructuredText) files: rst-tutorial
Transfer markdown to rst: md-to-rst

Troubleshooting¶

Maven can’t parse proxy correctly¶

If it raises error related to proxy by Maven, please ensure your settings.xml file (usually ${user.home}/.m2/settings.xml) is secured with permissions appropriate for your operating system.

Reference: https://maven.apache.org/guides/mini/guide-proxies.html

The Velox build failed issue¶

If it raises error on the code in velox/velox/core/Context.h, please modified the corresponding code like this:

enum class ContextScope { GLOBAL, SESSION, QUERY, SCOPESTACK };
saying: expected identifier before ‘,’ token, please make a modification:
enum class UseCase {
DEV = 1,
TEST = 2,
PROD = 3,
};

#ifdef GLOBAL
#undef GLOBAL
#endif
enum class ContextScope { GLOBAL, SESSION, QUERY, SCOPESTACK };