2017-10-16 21:28:38 +08:00
|
|
|
# WHAT ARCHITECTURE?
|
2011-05-11 21:13:55 +08:00
|
|
|
|
2015-10-05 23:49:47 +08:00
|
|
|
CPROVER now needs a C++11 compliant compiler and works in the following
|
|
|
|
environments:
|
2011-07-14 19:47:56 +08:00
|
|
|
|
2011-05-11 21:13:55 +08:00
|
|
|
- Linux
|
|
|
|
- MacOS X
|
2014-06-16 21:42:10 +08:00
|
|
|
- Solaris 11
|
2017-03-19 06:13:05 +08:00
|
|
|
- FreeBSD 11
|
2017-10-24 19:24:52 +08:00
|
|
|
- Cygwin
|
|
|
|
- Microsoft Visual Studio
|
2014-11-22 20:46:10 +08:00
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
The rest of this document is split up into three parts: compilation on Linux,
|
|
|
|
MacOS, Windows. Please read the section appropriate for your machine.
|
2011-05-11 21:13:55 +08:00
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
# COMPILATION ON LINUX
|
2011-05-11 21:13:55 +08:00
|
|
|
|
2013-12-11 23:03:32 +08:00
|
|
|
We assume that you have a Debian/Ubuntu or Red Hat-like distribution.
|
2011-05-11 21:13:55 +08:00
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
1. You need a C/C++ compiler, Flex and Bison, and GNU make.
|
2017-03-19 06:13:05 +08:00
|
|
|
The GNU Make needs to be version 3.81 or higher.
|
|
|
|
On Debian-like distributions, do
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2017-05-23 00:35:10 +08:00
|
|
|
apt-get install g++ gcc flex bison make git libwww-perl patch
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2014-10-14 20:14:34 +08:00
|
|
|
On Red Hat/Fedora or derivates, do
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2017-03-23 18:31:24 +08:00
|
|
|
yum install gcc gcc-c++ flex bison perl-libwww-perl patch devtoolset-6
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2017-04-25 17:09:31 +08:00
|
|
|
Note that you need g++ version 4.9 or newer.
|
2017-10-16 21:26:37 +08:00
|
|
|
2. As a user, get the CBMC source via
|
|
|
|
```
|
2016-04-03 00:18:30 +08:00
|
|
|
git clone https://github.com/diffblue/cbmc cbmc-git
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
|
|
|
3. On Debian or Ubuntu, do
|
|
|
|
```
|
2017-03-30 01:39:52 +08:00
|
|
|
cd cbmc-git/src
|
|
|
|
make minisat2-download
|
|
|
|
make
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2017-03-23 16:50:03 +08:00
|
|
|
On Redhat/Fedora etc., do
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2017-03-23 16:50:03 +08:00
|
|
|
cd cbmc-git/src
|
|
|
|
make minisat2-download
|
2017-03-23 18:31:24 +08:00
|
|
|
scl enable devtoolset-6 bash
|
|
|
|
make
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2017-03-23 16:50:03 +08:00
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
# COMPILATION ON SOLARIS 11
|
2013-12-11 23:03:32 +08:00
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
1. As root, get the necessary development tools:
|
|
|
|
```
|
2016-07-20 23:23:07 +08:00
|
|
|
pkg install system/header developer/lexer/flex developer/parser/bison developer/versioning/git
|
2017-04-02 19:15:25 +08:00
|
|
|
pkg install --accept developer/gcc/gcc-c++-5
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
|
|
|
2. As a user, get the CBMC source via
|
|
|
|
```
|
2016-04-03 00:18:30 +08:00
|
|
|
git clone https://github.com/diffblue/cbmc cbmc-git
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
|
|
|
3. Get MiniSat2 by entering
|
|
|
|
```
|
2016-04-03 00:18:30 +08:00
|
|
|
cd cbmc-git
|
2016-03-09 01:26:34 +08:00
|
|
|
wget http://ftp.debian.org/debian/pool/main/m/minisat2/minisat2_2.2.1.orig.tar.gz
|
|
|
|
gtar xfz minisat_2.2.1.orig.tar.gz
|
2016-07-20 23:23:07 +08:00
|
|
|
mv minisat2-2.2.1 minisat-2.2.1
|
2016-03-09 01:26:34 +08:00
|
|
|
(cd minisat-2.2.1; patch -p1 < ../scripts/minisat-2.2.1-patch)
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
|
|
|
4. Type
|
|
|
|
```
|
2016-07-20 23:23:07 +08:00
|
|
|
cd src; gmake
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2016-07-20 23:23:07 +08:00
|
|
|
That should do it. To run, you will need
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2016-07-20 23:23:07 +08:00
|
|
|
export LD_LIBRARY_PATH=/usr/gcc/4.9/lib
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2013-12-11 23:03:32 +08:00
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
# COMPILATION ON FREEBSD 11
|
2012-10-21 19:15:17 +08:00
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
1. As root, get the necessary tools:
|
|
|
|
```
|
2016-04-03 00:18:30 +08:00
|
|
|
pkg install bash gmake git www/p5-libwww patch flex bison
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
|
|
|
2. As a user, get the CBMC source via
|
|
|
|
```
|
2016-04-03 00:18:30 +08:00
|
|
|
git clone https://github.com/diffblue/cbmc cbmc-git
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
|
|
|
3. Do
|
|
|
|
```
|
2016-04-03 00:18:30 +08:00
|
|
|
cd cbmc-git/src
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
|
|
|
4. Do
|
|
|
|
```
|
2014-11-22 20:46:10 +08:00
|
|
|
gmake minisat2-download
|
|
|
|
gmake
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2014-11-22 20:46:10 +08:00
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
# COMPILATION ON MACOS X
|
2012-10-21 19:15:17 +08:00
|
|
|
|
|
|
|
Follow these instructions:
|
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
1. You need a C/C++ compiler, Flex and Bison, and GNU make. To this end, first
|
|
|
|
install the XCode from the App-store and then type
|
|
|
|
```
|
2016-01-13 03:50:20 +08:00
|
|
|
xcode-select --install
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2016-01-13 03:50:20 +08:00
|
|
|
in a terminal window.
|
2017-10-16 21:26:37 +08:00
|
|
|
2. Then get the CBMC source via
|
|
|
|
```
|
2016-04-03 00:18:30 +08:00
|
|
|
git clone https://github.com/diffblue/cbmc cbmc-git
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
|
|
|
3. Then type
|
|
|
|
```
|
2016-04-03 00:18:30 +08:00
|
|
|
cd cbmc-git/src
|
2014-12-08 19:39:31 +08:00
|
|
|
make minisat2-download
|
|
|
|
make
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2012-10-21 19:15:17 +08:00
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
# COMPILATION ON WINDOWS
|
2012-10-21 19:15:17 +08:00
|
|
|
|
2017-10-24 19:24:52 +08:00
|
|
|
There are two options: the Visual Studio compiler with version 12 (2013) or
|
|
|
|
later, or the MinGW cross compiler with version 5.4 or later.
|
|
|
|
We recommend Visual Studio.
|
2012-11-15 16:35:16 +08:00
|
|
|
|
2012-10-21 19:15:17 +08:00
|
|
|
Follow these instructions:
|
|
|
|
|
2017-10-24 19:24:52 +08:00
|
|
|
1. First install Cygwin, then from the Cygwin setup facility install the
|
|
|
|
following packages: `flex, bison, tar, gzip, git, make, wget, patch`.
|
|
|
|
2. Get the CBMC source via
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2017-10-24 19:24:52 +08:00
|
|
|
git clone https://github.com/diffblue/cbmc cbmc-git
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
2017-10-24 19:24:52 +08:00
|
|
|
3. Depending on your choice of compiler:
|
|
|
|
1. To compile with Visual Studio, change the second line of config.inc to
|
2017-10-16 21:26:37 +08:00
|
|
|
```
|
|
|
|
BUILD_ENV = MSVC
|
|
|
|
```
|
2017-10-24 19:24:52 +08:00
|
|
|
Open the Developer Command Prompt for Visual Studio, then start the
|
|
|
|
Cygwin shell with
|
|
|
|
```
|
|
|
|
bash.exe -login
|
|
|
|
```
|
|
|
|
2. To compile with MinGW, use Cygwin setup to install a mingw g++ compiler
|
|
|
|
package, i.e. one of `mingw{32,64}-{x86_64,i686}-gcc-g++`. Then start
|
|
|
|
the Cygwin shell.
|
|
|
|
4. In the Cygwin shell, type
|
|
|
|
```
|
|
|
|
cd cbmc-git/src
|
|
|
|
make DOWNLOADER=wget minisat2-download
|
|
|
|
make
|
|
|
|
```
|
2013-03-04 18:02:33 +08:00
|
|
|
|
2013-06-16 23:14:44 +08:00
|
|
|
(Optional) A Visual Studio project file can be generated with the script
|
2017-10-16 21:26:37 +08:00
|
|
|
"generate_vcxproj" that is in the subdirectory "scripts". The project file is
|
|
|
|
helpful for GUI-based tasks, e.g., the class viewer, debugging, etc., and can
|
|
|
|
be used for building with MSBuild. Note that you still need to run flex/bison
|
|
|
|
using "make generated_files" before opening the project.
|
2014-10-31 02:33:40 +08:00
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
# WORKING WITH CMAKE (EXPERIMENTAL)
|
2017-08-25 01:24:15 +08:00
|
|
|
|
|
|
|
There is an experimental build based on CMake instead of hand-written
|
|
|
|
makefiles. It should work on a wider variety of systems than the standard
|
|
|
|
makefile build, and can integrate better with IDEs and static-analysis tools.
|
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
1. Run `cmake --version`. If you get a command-not-found error, or the
|
|
|
|
installed version is lower than 3.2, go and install a new version. Most
|
|
|
|
Linux distributions have a package for CMake, and Mac users can get it
|
|
|
|
through Homebrew. Windows users should download it manually from cmake.org.
|
|
|
|
2. Create a directory to store your build:
|
|
|
|
```
|
|
|
|
mkdir build
|
|
|
|
```
|
2017-08-25 01:24:15 +08:00
|
|
|
Run this from the *top level* folder of the project. This is different from
|
|
|
|
the other builds, which require you to `cd src` first.
|
2017-10-16 21:26:37 +08:00
|
|
|
3. Generate build files with CMake:
|
|
|
|
```
|
|
|
|
cmake -H. -Bbuild
|
|
|
|
```
|
2017-08-25 01:24:15 +08:00
|
|
|
This command tells CMake to use the configuration in the current directory,
|
2017-10-16 21:26:37 +08:00
|
|
|
and to generate build files into the `build` directory. This is the point
|
|
|
|
to specify custom build settings, such as compilers and build back-ends. You
|
|
|
|
can use clang (for example) by adding the argument
|
|
|
|
`-DCMAKE_CXX_COMPILER=clang++` to the command line. You can also tell CMake
|
|
|
|
to generate IDE projects by supplying the `-G` flag. Run `cmake -G` for a
|
|
|
|
comprehensive list of supported back-ends.
|
2017-08-25 01:24:15 +08:00
|
|
|
|
|
|
|
Generally it is not necessary to manually specify individual compiler or
|
2017-10-16 21:26:37 +08:00
|
|
|
linker flags, as CMake defines a number of "build modes" including Debug and
|
|
|
|
Release modes. To build in a particular mode, add the flag
|
2017-08-25 01:24:15 +08:00
|
|
|
`-DCMAKE_BUILD_TYPE=Debug` (or `Release`) to the initial invocation.
|
|
|
|
|
|
|
|
If you *do* need to manually add flags, use `-DCMAKE_CXX_FLAGS=...` and
|
|
|
|
`-DCMAKE_EXE_LINKER_FLAGS=...`. This is useful for enabling clang's
|
|
|
|
sanitizers.
|
|
|
|
|
|
|
|
Finally, to enable building universal binaries on macOS, you can pass the
|
|
|
|
flag `-DCMAKE_OSX_ARCHITECTURES=i386;x86_64`. If you don't supply this flag,
|
|
|
|
the build will just be for the architecture of your machine.
|
2017-10-16 21:26:37 +08:00
|
|
|
4. Run the build:
|
|
|
|
```
|
|
|
|
cmake --build build
|
|
|
|
```
|
2017-08-25 01:24:15 +08:00
|
|
|
This command tells CMake to invoke the correct tool to run the build in the
|
|
|
|
`build` directory. You can also use the build back-end directly by invoking
|
|
|
|
`make`, `ninja`, or opening the generated IDE project as appropriate.
|
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
# WORKING WITH ECLIPSE
|
2014-10-31 02:33:40 +08:00
|
|
|
|
|
|
|
To work with Eclipse, do the following:
|
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
1. Select File -> New -> Makefile Project with Existing Code
|
|
|
|
2. Type "cprover" as "Project Name"
|
|
|
|
3. Select the "src" subdirectory as "Existing Code Location"
|
|
|
|
4. Select a toolchain appropriate for your platform
|
|
|
|
5. Click "Finish"
|
|
|
|
6. Select Project -> Build All
|
2017-01-04 21:36:14 +08:00
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
# CODE COVERAGE
|
2017-01-04 21:36:14 +08:00
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
Code coverage metrics are provided using gcov and lcov. Ensure that you have
|
|
|
|
installed lcov from http://ltp.sourceforge.net/coverage/lcov.php note for
|
|
|
|
ubuntu lcov is available in the standard apt-get repos.
|
2017-01-04 21:36:14 +08:00
|
|
|
|
2017-10-16 21:26:37 +08:00
|
|
|
To get coverage metrics run the following script from the regression directory:
|
|
|
|
```
|
|
|
|
get_coverage.sh
|
|
|
|
```
|
2017-01-04 21:36:14 +08:00
|
|
|
This will:
|
|
|
|
1) Rebuild CBMC with gcov enabled
|
|
|
|
2) Run all the regression tests
|
|
|
|
3) Collate the coverage metrics
|
|
|
|
4) Provide an HTML report of the current coverage
|
2017-10-16 21:28:38 +08:00
|
|
|
|
|
|
|
# USING CLANG-FORMAT
|
|
|
|
|
|
|
|
CBMC uses clang-format to ensure that the formatting of new patches is readable
|
|
|
|
and consistent. There are two main ways of running clang-format: remotely, and
|
|
|
|
locally.
|
|
|
|
|
|
|
|
## RUNNING CLANG-FORMAT REMOTELY
|
|
|
|
|
|
|
|
When patches are submitted to CBMC, they are automatically run through
|
|
|
|
continuous integration (CI). One of the CI checks will run clang-format over
|
|
|
|
the diff that your pull request introduces. If clang-format finds formatting
|
|
|
|
issues at this point, the build will be failed, and a patch will be produced
|
|
|
|
in the CI output that you can apply to your code so that it conforms to the
|
|
|
|
style guidelines.
|
|
|
|
|
|
|
|
To apply the patch, copy and paste it into a local file (`patch.txt`) and then
|
|
|
|
run:
|
|
|
|
```
|
|
|
|
patch -p1 -i patch.txt
|
|
|
|
```
|
|
|
|
Now, you can commit and push the formatting fixes.
|
|
|
|
|
|
|
|
## RUNNING CLANG-FORMAT LOCALLY
|
|
|
|
|
|
|
|
### INSTALLATION
|
|
|
|
|
|
|
|
To avoid waiting until you've made a PR to find formatting issues, you can
|
|
|
|
install clang-format locally and run it against your code as you are working.
|
|
|
|
|
|
|
|
Different versions of clang-format have slightly different behaviors. CBMC uses
|
|
|
|
clang-format-3.8 as it is available the repositories for Ubuntu 16.04 and
|
|
|
|
Homebrew.
|
2017-10-19 17:02:27 +08:00
|
|
|
To install on a Unix-like system, try installing using the system package
|
|
|
|
manager:
|
2017-10-16 21:28:38 +08:00
|
|
|
```
|
2017-10-19 17:02:27 +08:00
|
|
|
apt-get install clang-format-3.8 # Run this on Ubuntu, Debian etc.
|
|
|
|
brew install clang-format@3.8 # Run this on a Mac with Homebrew installed
|
2017-10-16 21:28:38 +08:00
|
|
|
```
|
|
|
|
|
2017-10-19 17:02:27 +08:00
|
|
|
If your platform doesn't have a package for clang-format, you can download a
|
|
|
|
pre-built binary, or compile clang-format yourself using the appropriate files
|
|
|
|
from the [LLVM Downloads page](http://releases.llvm.org/download.html).
|
|
|
|
|
|
|
|
An installer for Windows (along with a Visual Studio plugin) can be found at
|
|
|
|
the [LLVM Snapshot Builds page](http://llvm.org/builds/).
|
|
|
|
|
2017-10-16 21:28:38 +08:00
|
|
|
### FORMATTING A RANGE OF COMMITS
|
|
|
|
|
|
|
|
Clang-format is distributed with a driver script called git-clang-format-3.8.
|
|
|
|
This script can be used to format git diffs (rather than entire files).
|
|
|
|
|
|
|
|
After committing some code, it is recommended to run:
|
|
|
|
```
|
|
|
|
git-clang-format-3.8 upstream/develop
|
|
|
|
```
|
|
|
|
*Important:* If your branch is based on a branch other than `upstream/develop`,
|
|
|
|
use the name or checksum of that branch instead. It is strongly recommended to
|
|
|
|
rebase your work onto the tip of the branch it's based on before running
|
|
|
|
`git-clang-format` in this way.
|
|
|
|
|
|
|
|
### RETROACTIVELY FORMATTING INDIVIDUAL COMMITS
|
|
|
|
|
|
|
|
If your works spans several commits and you'd like to keep the formatting
|
|
|
|
correct in each individual commit, you can automatically rewrite the commits
|
|
|
|
with correct formatting.
|
|
|
|
|
|
|
|
The following command will stop at each commit in the range and run
|
|
|
|
clang-format on the diff at that point. This rewrites git history, so it's
|
|
|
|
*unsafe*, and you should back up your branch before running this command:
|
|
|
|
```
|
|
|
|
git filter-branch --tree-filter 'git-clang-format-3.8 upstream/develop' \
|
|
|
|
-- upstream/develop..HEAD
|
|
|
|
```
|
|
|
|
*Important*: `upstream/develop` should be changed in *both* places in the
|
|
|
|
command above if your work is based on a different branch. It is strongly
|
|
|
|
recommended to rebase your work onto the tip of the branch it's based on before
|
|
|
|
running `git-clang-format` in this way.
|