From 2d8c995609211ba16d1c37b4384f3299bc770203 Mon Sep 17 00:00:00 2001 From: Ian A Mason Date: Wed, 12 Jul 2017 14:34:09 -0700 Subject: [PATCH] Update README.md --- README.md | 50 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 8b2309a..94678db 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![Build Status](https://travis-ci.org/SRI-CSL/gllvm.svg?branch=master)](https://travis-ci.org/SRI-CSL/gllvm) [![Go Report Card](https://goreportcard.com/badge/github.com/SRI-CSL/gllvm)](https://goreportcard.com/report/github.com/SRI-CSL/gllvm) -**TL; DR:** A *fast* concurrent drop-in replacement for [wllvm](https://github.com/SRI-CSL/whole-program-llvm) without dragonegg support. +**TL; DR:** A *fast* concurrent drop-in replacement for [wllvm](https://github.com/SRI-CSL/whole-program-llvm), without dragonegg support. ## Overview @@ -61,6 +61,7 @@ FIXME: this needs to be rewritten to use spells like this: go get github.com/SRI-CSL/gllvm/cmd/gclang go get github.com/SRI-CSL/gllvm/cmd/gclang++ go get github.com/SRI-CSL/gllvm/cmd/get-bc +go get github.com/SRI-CSL/gllvm/cmd/gsanity-check ``` First, you must checkout the project under the directory `$GOROOT/src`: @@ -76,31 +77,31 @@ make install ## Usage -gllvm includes three symlinks to the program's binary: `gclang` and -`gclang++`to compile C and C++, and an auxiliary tool `get-bc` for +gllvm provides four binaries: `gclang` and +`gclang++` to compile C and C++, an auxiliary tool `get-bc` for extracting the bitcode from a build product (object file, executable, library -or archive). +or archive), and a sanity checker, `gsanity-check` for detecting configuration oversights.. Some useful environment variables are listed here: - * `GLLVM_CC_NAME` can be set if your clang compiler is not called `clang` but - something like `clang-3.7`. Similarly `GLLVM_CXX_NAME` can be used to + * `LLVM_CC_NAME` can be set if your clang compiler is not called `clang` but + something like `clang-3.7`. Similarly `LLVM_CXX_NAME` can be used to describe what the C++ compiler is called. We also pay attention to the - environment variables `GLLVM_LINK_NAME` and `GLLVM_AR_NAME` in an + environment variables `LLVM_LINK_NAME` and `LLVM_AR_NAME` in an analagous way, since they too get adorned with suffixes in various Linux distributions. - * `GLLVM_TOOLS_PATH` can be set to the absolute path to the folder that + * `LLVM_COMPILER_PATH` can be set to the absolute path to the folder that contains the compiler and other LLVM tools such as `llvm-link` to be used. This prevents searching for the compiler in your PATH environment variable. This can be useful if you have different versions of clang on your system and you want to easily switch compilers without tinkering with your PATH variable. - Example `GLLVM_TOOLS_PATH=/home/user/llvm_and_clang/Debug+Asserts/bin`. + Example `LLVM_COMPILER_PATH=/home/user/llvm_and_clang/Debug+Asserts/bin`. -* `GLLVM_CONFIGURE_ONLY` can be set to anything. If it is set, `gclang` +* `WLLVM_CONFIGURE_ONLY` can be set to anything. If it is set, `gclang` and `gclang++` behave like a normal C or C++ compiler. They do not - produce bitcode. Setting `GLLVM_CONFIGURE_ONLY` may prevent configuration + produce bitcode. Setting `WLLVM_CONFIGURE_ONLY` may prevent configuration errors caused by the unexpected production of hidden bitcode files. It is sometimes required when configuring a build. @@ -149,10 +150,10 @@ produces `src/LinearMath/libLinearMath.a.bc`. Sometimes it is necessary to disable the production of bitcode. Typically this is during configuration, where the production of unexpected files can confuse -the configure script. For this we have a flag `GLLVM_CONFIGURE_ONLY` which +the configure script. For this we have a flag `WLLVM_CONFIGURE_ONLY` which can be used as follows: ``` -GLLVM_CONFIGURE_ONLY=1 CC=gclang ./configure +WLLVM_CONFIGURE_ONLY=1 CC=gclang ./configure CC=gclang make ``` @@ -178,7 +179,7 @@ ls -la Sometimes it can be useful to preserve the bitcode files produced in a build, either to prevent deletion or to retrieve them later. If the -environment variable `GLLVM_BC_STORE` is set to the absolute path of +environment variable `WLLVM_BC_STORE` is set to the absolute path of an existing directory, then gllvm will copy the produced bitcode files into that directory. The name of a copied bitcode file is the hash of the path to the original bitcode file. For convenience, when using both the manifest @@ -190,7 +191,7 @@ original path, and the store path. The GLLVM tools can show various levels of output to aid with debugging. -To show this output set the `GLLVM_OUTPUT_LEVEL` environment +To show this output set the `WLLVM_OUTPUT_LEVEL` environment variable to one of the following levels: * `ERROR` @@ -200,12 +201,25 @@ variable to one of the following levels: For example: ``` - export GLLVM_OUTPUT_LEVEL=DEBUG + export WLLVM_OUTPUT_LEVEL=DEBUG ``` Output will be directed to the standard error stream, unless you specify the -path of a logfile via the `GLLVM_OUTPUT_FILE` environment variable. +path of a logfile via the `WLLVM_OUTPUT_FILE` environment variable. For example: ``` - export GLLVM_OUTPUT_FILE=/tmp/gllvm.log + export WLLVM_OUTPUT_FILE=/tmp/gllvm.log ``` +### Sanity Checking + +Too many environment variables? Try doing a sanity check: + +``` +gsanity-check +``` +it might point out what is wrong. + + +### License + +GLLVM is released under the MIT license. See the file `LICENSE` for [details.](LICENSE)