project create¶

So far, It is difficult to create a CMake managed project. Some Project nearly 1000 LOC to write. For a parts of EA, carbin take the work of project management, specially, for generation plugins, we do not want to write cmake building system manually and take to long time, it seem to done in just one second. carbin done this.

carbin make you known less CMake but using it smartly. only remind that,

what is my source files.
what library name I want to create
what dependencies I need to link

when you create a library, using find_package(you_project REQUIRED). ok that is the all!

create a project¶

Suppose that we want to create a project named exodus, which powered by cmake.

carbin create --name exodus --test --examples --benchmark --requirements

carbin will first download the carbin cmake template cmake template, and then, change every as you want to, then write file to current dir.

ll and look at the dir:

drwxrwxr-x  2 jeff jeff 4096 4月  15 18:49 benchmark/
drwxrwxr-x  9 jeff jeff 4096 4月  15 18:49 build/
drwxrwxr-x  3 jeff jeff 4096 4月  15 18:49 carbin/
drwxrwxr-x  7 jeff jeff 4096 4月  15 18:49 carbin_cmake/
-rw-rw-r--  1 jeff jeff 1559 4月  15 18:49 carbin_deps.txt
drwxrwxr-x  2 jeff jeff 4096 4月  15 18:49 cmake/
-rw-rw-r--  1 jeff jeff 5373 4月  15 18:49 CMakeLists.txt
drwxrwxr-x  2 jeff jeff 4096 4月  15 18:49 conda/
drwxrwxr-x  2 jeff jeff 4096 4月  15 18:49 examples/
drwxrwxr-x  2 jeff jeff 4096 4月  15 18:49 exodus/
drwxrwxr-x  2 jeff jeff 4096 4月  15 18:49 tests/

you can do:

mkdir build
cd build
cmake ..
make
make test

try it out~

most possibility you need to modify is exodus/CMakeList.txt and file in cmake dir:

-rw-rw-r--  1 jeff jeff 1653 4月  15 18:49 exodus_cxx_config.cmake
-rw-rw-r--  1 jeff jeff 1341 4月  15 18:49 exodus_deps.cmake
-rw-rw-r--  1 jeff jeff  760 4月  15 18:49 exodus_test.cmake

the exodus_cxx_config.cmake configs for c/c++ or asm compile flags and options.
exodus_deps.cmake configs the dependencies libraries linking
exodus_test.cmake configs what test to run.

create_library¶

carbin create both static and shared library all, but do not worry that cost it just build all the source to object, for C/C++ it is .o file, and then ,link them to libs.

now let see the function examples at exodus/CMakeLists.txt:

carbin_cc_library(
    NAMESPACE exodus
    NAME share
    SOURCES
    shared.cc
    CXXOPTS
    ${CARBIN_CXX_OPTIONS}
    DEPS
    exodus::object
    PLINKS
    ${CARBIN_DEPS_LINK}
    exodus::object

)

this code create a library name share and export to namespace exodus. lets see the arguments.

NAMESPACE usually is project name, do care it.
NAME you library name, it should be unique in you project
SOURCES c/c++ file list can be shared.cc static.cc etc.
CXXOPTS c++ compile option.
COPTS c compile option.
CUOPTS cuda compile option.
DEPS condition options, for example, lib B need A compile complete, etc…
LINKS public links, for example link to openssl’s dynamic lib, the caller need link it to
PLINKS private links, it only refence to you source code, for example, you compile a inner lib name hello.a just you lib call
the hello define in that lib.
OBJECTS object file’name create by add_library(xxx OBJECT aa.cc) or create by the sibling function of carbin_cc_library
carbin_cc_object
WLINKS this is a using for that to hidden backend libray, it means load these static libraries symbal to you lib. for example,
you lib ref to zlib, when you expose all zlib’s symbal, all zlibstatic found by find_package to WLINKS, thus you lib contains zlib. who ref to lib, do not need to link to zlib, you are the world.
DEFINES means add defines to you code, eg. NDEBUG
INCLUDES public include dirs
PINCLUDES private include dirs, a simple rule is that, if you header have include the file, using public, else using private
EXCLUDE_SYSTEM option flag, means do not add -isystem flags to gcc.
PUBLIC means this library will be installed and export. for example, a test only lib just for you test do not mark this.

carbin_cc_object¶

Almost the some as carbin_cc_library, almost the some means of it arguments, but this only compile source file to object, the exemple see the obm_source and obm_no_source. remember that, it do not product complete produce, but Semi-finished products.

carbin_cc_interface¶

the header only library, if you do not have source code ,using this one.

library install¶

carbin_cc_* have already write installer, you no need to write install, headers are installed instructions at the last of the main CMakeList.txt, if you want to install other things, write instructions before or after headers installation nay be a good idea.

targets export and find package¶

the template also export targets for you, once you lib is installed, the other caller can using `find_package(exodus REQUIRED), so the guy whill get exodus::shared and other targets.

also, ${exodus_INCLUDE_DIR} is expose to the guy, she can include it in cmake.

testing¶

the test examples see the tests dir, if you want disable the whole project test, mark CARBIN_BUILD_TEST=OFF defined in carbin_option.cmake.

like this:

cmake .. -DCARBIN_BUILD_TEST=OFF

if you just want to disable a sigal test, just mark the test DISABLED like the test:

carbin_cc_test(
    NAME pass_test
    MODULE base
    SOURCES pass_test.cc
    DISABLED
)

by default carbin_cc_test create a test case by MODULE + _ + NAME executable binary,and run with no arguments. like above ,it will create base_pass_test and run ./base_pass_test if not mark DISABLED.

some time the test case need commandline arguments, we offer it by two steps, first using carbin_cc_test compile binary by mark it with EXT like this:

carbin_cc_test(
    NAME args_test
    MODULE base
    SOURCES args_test.cc
    EXT
)

this will not generate default. and the using carbin_cc_test_ext to generate test case with arguments. like this:

carbin_cc_test_ext(
    NAME args_test
    MODULE base
    ALIAS skip
    ARGS "SKIP"
    PASS_EXP "pass;Passed"
    FAIL_EXP "[^a-z]Error;ERROR;Failed"
    SKIP_EXP "[^a-z]Skip" "SKIP" "Skipped"
)

PASS_EXP FAIL_EXP SKIP_EXP expression is the regex to test the test output to stdout, success or not, It will be more intuitive to run make test directly to view the screen output.

batch skip testing¶

some time, for testing, we do not run all case, for we fix some case, we just want run this case. carbin_cc_test’s MODULE comes into play at this time, for example, put all your test in two group do_run no_run, mark the you wan to test do_run and the see the cmake/exodus.cmake, put no_run to the ${PROJECT_NAME}_SKIP_TEST, check out that file and you’ll understand everything. the benchmark is the same as testing.