Project: YugabyteDB (App Definition and Development / Database)
File: build-and-test.md

title: Build and test headerTitle: Build and test linkTitle: Build and test description: Build and test headcontent: Building and testing with yb_build.sh. aliases: /preview/contribute/core-database/run-unit-tests/ menu: preview: identifier: build-and-test parent: core-database weight: 2913 type: docs `yb_build.sh` is a bash script for both building and testing. Some flags can turn off certain parts of build, and other flags can decide which tests to run. In general, they come down to these components: build: C++: C++ code in `src/yb/` and `ent/src/yb` for `yb-master`, `yb-tserver`, `yb-admin`, test binaries, etc. postgres: C code in `src/postgres/` for `postgres`, `ysqldump`, `libybpgbackend`, `libpq`, etc. Java: Java code in `java/` for CDC, Java tests, drivers, etc. `initdb`: pre-created initial system catalog snapshot for YSQL test: C++ tests Java tests For a full list of options, run `yb_build.sh -h`. What follows are some of the common options to pay attention to. By default, all items are built. You can specify a target to narrow down what to build. See `./yb_build.sh -h` for the supported targets. Besides that, certain flags may skip building some items. For example, specifying a flag to run a C++ test skips the Java build (but running a Java test won't skip the C++ build). Although there is some intelligence to avoid rebuilding parts, it is incomplete. For example, the postgres build uses a build stamp calculated from a git commit and working changes; if there is a mismatch, it reruns postgres configure and make. The Java build always runs the full build. Use the `--skip-cxx-build`/`--scb` and `--skip-java-build`/`--sj` flags to reduce incremental build times. `initdb` is a special case because it is only built if it hasn't been built before, but it isn't rebuilt again unless the `reinitdb` target is specified. You should run `reinitdb` in case the initial system catalog in the source code is different since the last time `initdb` was run, unless you intentionally want to use the old initial system catalog (for example, to test upgrades). CMake is used. By default, `ninja` is used, but `make` is also supported. Specify the build tool using the `--make` and `--ninja` flags. The following build types are available: debug (the default) release fastdebug: fewer compiler optimizations and a few other tweaks on debug asan: address sanitizer tsan: thread sanitizer By default, `clang` is used, but `gcc` is also supported. Specify the compiler using the `--gcc<versionnumber>` and `--clang<versionnumber>` flags. The specific versions supported can be found in `./build-support/third-party-archives.yml`, which details the configurations regularly tested in-house. By default, third-party libraries are pre-built into archives, and those archives are downloaded to be used during

Incremental builds currently do not detect when the third-party archive URL has been updated, so when that happens, you should run a `--clean` build to use the new third-party archive. You can also build the third-party archives locally using `--no-download-thirdparty` or `--ndltp`. The following examples use the `release` build type, but any build type can be specified, provided that build type is not disabled for that test. For example, several tests are disabled for the `tsan` build type. By default, the `yb_build.sh` commands to run C++ tests will first build those tests. Build can be avoided using `--skip-cxx-build` or `--scb`. To run all the C++ tests, run the following command: ```sh ./yb_build.sh release --ctest ``` To run a specific test, for example the `util_monotime-test` test, run the following command: ```sh ./ybbuild.sh release --cxx-test utilmonotime-test ``` To run a specific sub-test, for example the `TestMonoTime.TestCondition` sub-test in `util_monotime-test`, run the following command: ```sh ./ybbuild.sh release --cxx-test utilmonotime-test --gtest_filter TestMonoTime.TestCondition ``` `--gtest_filter` supports globbing. For example, `TestMonoTime.TestTime*` runs both `TestMonoTime.TestTimeVal` and `TestMonoTime.TestTimeSpec`. Make sure to escape or quote the `*` if your shell interprets it as a glob character. By default, the `yb_build.sh` commands to run Java tests will first build key C++ targets and do the full Java build. Build can be avoided using `--skip-cxx-build`/`--scb` and `--skip-java-build`/`--sj`. To run all the Java tests, use the following command: ```sh ./yb_build.sh release --java-tests ``` To run a specific test: ```sh ./yb_build.sh release --java-test org.yb.client.TestYBClient ``` To run a specific Java sub-test within a test file, use the # syntax. For example: ```sh ./yb_build.sh release --java-test 'org.yb.client.TestYBClient#testClientCreateDestroy' ``` `--scb` and `--sj` are recommended in case the C++ and Java code was already built beforehand. `yb_build.sh` has a built-in capability of running tests multiple times with parallelism. `--num_repetitions`/`-n`: number of times to run the test(s) `--test-parallelism`/`--tp`: number of instances of the test to run in parallel Note that a high parallelism could result in failures if system resources are overused. C++ tests are located in `src/yb` or `ent/src/yb` and end in `test.cc`. Many C++ tests use external mini cluster or mini cluster to create clusters. A key difference is that external mini clusters create separate master, tserver, and postgres processes (as in real life), while mini clusters create masters and tservers within the same process and optionally spawn a separate postgres process. Use external mini clusters instead of mini clusters unless you have a specific reason to do otherwise, such as: you need access to catalog manager internals there is little to no YSQL usage and speed is more important YSQL Java tests are located in

Some of those tests, named `TestPgRegress*`, use the PostgreSQL regress test framework (see `src/postgres/src/test/regress`). They each correspond to a schedule (for example, `java/yb-pgsql/src/test/java/org/yb/pgsql/TestPgRegressArrays.java` references `src/postgres/src/test/regress/ybarraysschedule`) that is run by our modified version of `pg_regress`. Each schedule lists a serial order of test files to run. The same cluster is used for the whole schedule, but a new SQL connection is made for each test file. The test framework does the following: Copies test files from the `src` directory to the `build` directory (this is technically done as part of build). Copies test files to a temporary `test` directory. In the `test` directory, generates `sql`/`expected` from `input`/`output` In the `test` directory, generates `results` by running tests in `sql`. Copies back `results` from the `test` directory to the `build` directory. Deletes the `test` directory. The files in `results` are compared with those in `expected` to determine pass/fail. {{< tip title="Tips" >}} To quickly run a specific SQL file, create a dummy Java file and dummy schedule with that one test in it. Use the following naming convention (some older files haven't adopted it yet, but should): `sql/foo.sql`: Unchanged from original PostgreSQL code. `sql/yb_foo.sql`: Completely new file (for example, with new features). `sql/ybpgfoo.sql`: Modified version of original PostgreSQL foo.sql (for example, with compatibility edits). The goal here is to reduce the difference between `foo.sql` and `ybpgfoo.sql`, when possible. {{< /tip >}} The general hierarchy of flags is as follows: Test framework: the framework may specify some default flags. Test superclass: any parent classes of the test class can set flags. Test subclass: child class flags should take precedence over parent class flags. Test: a test itself may set flags. User: the user running the test could add flags. There may be some areas where the order of precedence is not followed: help fixing this is welcome. Some of the ways in which you can specify flags to tests (uppercase are environment variables) are as follows: `YBEXTRADAEMON_FLAGS`, `--extra-daemon-flags`, `--extra-daemon-args`: pass flags to master and tserver processes. (This does not work on mini cluster.) `YBEXTRAMASTER_FLAGS`: pass flags to master processes. (Does not work on mini cluster.) `YBEXTRATSERVER_FLAGS`: pass flags to tserver processes. (Does not work on mini cluster.) `--test-args`: for C++ tests, pass flags to the test process. (For mini cluster, it also affects masters/tservers since they share the same process.) `YBEXTRAMVNOPTIONSIN_TESTS`, `--java-test-args`: for Java tests, pass flags in the form of Maven system parameters. Here are some examples: ```sh YBEXTRADAEMONFLAGS="--logysqlcatalogversions=true" \ YBEXTRAMASTERFLAGS="--vmodule=masterheartbeat_service=2" \ YBEXTRATSERVER_FLAGS="--vmodule=heartbeater=2" \ ./yb_build.sh \ --cxx-test pgwrapperpglibpq-test \ --gtest_filter PgLibPqTest.DBCatalogVersion ``` ```sh ./yb_build.sh \ --cxx-test integration-testsmasterfailover-itest \ --gtest_filter MasterFailoverTest.DereferenceTasks \ --test-args "--vmodule=masterfailover-itest=1,catalogmanager=4" ``` ```sh export YBEXTRAMVNOPTIONSIN_TESTS="-Dstyle.color=always" ./yb_build.sh \ --java-test TestPgRegressPgMisc \ --java-test-args "-Dyb.javatest.keepdata=true" ```