Skip to content

Commit 9f03580

Browse files
ianamasonianamason
committed
2 parents 555105b + bf0dce8 commit 9f03580

30 files changed

+618
-170
lines changed

‎.travis.yml

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,35 @@
11
language: python
2+
3+
sudo: required
4+
dist: trusty
5+
26
python:
37
- "3.3"
48
- "2.7"
59
- "2.6"
610

11+
712
# command to install dependencies
813
install:
914
- sudo apt-get update
10-
- sudo apt-get install llvm-3.4 clang-3.4 libapr1-dev libaprutil1-dev
11-
- sudo apt-get install dragonegg llvm-3.0 llvm-gcc
15+
# to install wllvm
16+
- sudo apt-get install -y python-pip
17+
# apache prerequisites
18+
- sudo apt-get install -y libapr1-dev libaprutil1-dev
19+
# for the clang build
20+
- sudo apt-get install -y llvm-3.5 clang-3.5
21+
# dragonegg prereqs. dragonegg and llvm-gcc use llvm 3.3
22+
- sudo apt-get install -y llvm-3.3 llvm-gcc-4.7
23+
- sudo pip install -e .
1224
- export WLLVM_HOME=`pwd`
25+
- export APACHE_VER=2.4.18
26+
1327

1428
# command to run tests
1529
script:
16-
# build apache with clang (i.e. httpd-2.4.12)
30+
# build apache with clang
1731
- ${WLLVM_HOME}/.travis/apache_clang.sh
18-
# build apache with gcc and dragonegg (i.e. httpd-2.4.12)
32+
# build apache with gcc and dragonegg
1933
- ${WLLVM_HOME}/.travis/apache_dragonegg.sh
2034

2135

‎.travis/apache_clang.sh

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,10 @@
33
set -e
44

55

6-
export PATH=/usr/lib/llvm-3.4/bin:${WLLVM_HOME}:${PATH}
6+
export PATH=/usr/lib/llvm-3.5/bin:${PATH}
77
export LLVM_COMPILER=clang
88
export WLLVM_OUTPUT=WARNING
99

10-
APACHE_VER=2.4.18
1110
wget https://archive.apache.org/dist/httpd/httpd-${APACHE_VER}.tar.gz
1211

1312
tar xfz httpd-${APACHE_VER}.tar.gz

‎.travis/apache_dragonegg.sh

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,13 @@ set -e
44

55
export dragonegg_disable_version_check=true
66

7-
export PATH=/usr/lib/llvm-3.0/bin:${WLLVM_HOME}:${PATH}
7+
export PATH=/usr/lib/llvm-3.3/bin:${PATH}
88
export LLVM_COMPILER=dragonegg
99
export LLVM_GCC_PREFIX=llvm-
10-
export LLVM_DRAGONEGG_PLUGIN=/usr/lib/gcc/x86_64-linux-gnu/4.6/plugin/dragonegg.so
10+
export LLVM_DRAGONEGG_PLUGIN=/usr/lib/gcc/x86_64-linux-gnu/4.7/plugin/dragonegg.so
1111

1212
export WLLVM_OUTPUT=WARNING
1313

14-
APACHE_VER=2.4.18
1514
wget https://archive.apache.org/dist/httpd/httpd-${APACHE_VER}.tar.gz
1615

1716

‎LICENSE

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
Copyright (c) 2013-2016 Ian A. Mason, Tristan Ravitch, Bruno Dutertre
12
Copyright (c) 2011-2013 Tristan Ravitch
23
Copyright (c) 2013 Ben Liblit, Daniel Liew
34

‎MANIFEST.in

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
include wllvm/dragonegg_as/as
2+

‎Makefile

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
2+
all:
3+
@echo ''
4+
@echo 'Here are the targets:'
5+
@echo ''
6+
@echo 'To develop : "make develop"'
7+
@echo 'To test install : "make testinstall"'
8+
@echo 'To install : "make install"'
9+
@echo 'To test publish : "make testpublish"'
10+
@echo 'To publish : "make publish"'
11+
12+
@echo 'To check clang : "make check_clang"'
13+
@echo ''
14+
@echo 'e.g. on linux: LLVM_COMPILER_PATH=/usr/lib/llvm-3.5/bin/ make check_clang'
15+
@echo ''
16+
@echo 'To check dragonegg : "make check_dragonegg"'
17+
@echo ''
18+
@echo 'e.g. on linux: PATH=/usr/lib/llvm-3.3/bin:... make check_dragonegg'
19+
@echo ''
20+
@echo 'To turn md 2 html : "make zippity"'
21+
@echo ''
22+
@echo 'then upload the zip file to https://pypi.python.org/pypi'
23+
@echo ''
24+
25+
26+
27+
#local editable install for developing
28+
develop:
29+
pip install -e .
30+
31+
32+
dist: clean
33+
python setup.py bdist_wheel
34+
35+
# If you need to push this project again,
36+
# INCREASE the version number in wllvm/version.py,
37+
# otherwise the server will give you an error.
38+
39+
testpublish: dist
40+
python setup.py register -r https://testpypi.python.org/pypi
41+
python setup.py sdist upload -r https://testpypi.python.org/pypi
42+
43+
testinstall:
44+
pip install -i https://testpypi.python.org/pypi wllvm
45+
46+
publish: dist
47+
python setup.py register -r https://pypi.python.org/pypi
48+
python setup.py sdist upload -r https://pypi.python.org/pypi
49+
50+
install:
51+
pip install
52+
53+
check_clang:
54+
cd test; python -m unittest -v test_base_driver test_clang_driver
55+
56+
check_dragonegg:
57+
cd test; python -m unittest -v test_base_driver test_dragonegg_driver
58+
59+
60+
zippity:
61+
rm -rf doczip*; mkdir doczip;
62+
cat README.md | pandoc -f markdown_github > doczip/index.html
63+
zip -r -j doczip.zip doczip
64+
65+
clean:
66+
rm -f wllvm/*.pyc wllvm/*~
67+
68+

‎README.md

Lines changed: 55 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,29 @@ of a build process requires that.
3131

3232
WLLVM works with either clang or the gcc dragonegg plugin.
3333

34+
Installation
35+
============
36+
37+
As of August 2016 WLLVM is now a pip package. You can just do:
38+
39+
pip install wllvm
40+
41+
42+
If you want to develop or use the development version:
43+
44+
git clone https://github.com/SRI-CSL/whole-program-llvm
45+
cd whole-program-llvm
46+
pip install -e .
47+
48+
3449
Usage
3550
=====
3651

3752
WLLVM includes two python executables: `wllvm` for compiling C code
38-
and `wllvm++` for C++, and an auxiliary tool `extract-bc`.
53+
and `wllvm++` for compiling C++, and an auxiliary tool `extract-bc` for
54+
extracting the bitcode from a build product (object file, executable, library
55+
or archive). There is also a sanity checker, `wllvm-sanity-checker` for detecting
56+
configuration oversights.
3957

4058
Three environment variables must be set to use these wrappers:
4159

@@ -74,6 +92,9 @@ In addition to the above environment variables the following can be optionally u
7492
bitcode files.
7593

7694

95+
96+
97+
7798
Building a bitcode module with clang
7899
====================================
79100

@@ -84,11 +105,18 @@ Building a bitcode module with clang
84105
CC=wllvm ./configure
85106
make
86107

87-
# Produces pkg-config.bc
108+
This should produce the executable `pkg-config`. To extract the bitcode:
109+
88110
extract-bc pkg-config
89111

90-
A gentler set of instructions on building apache can be found
91-
[here.](https://github.com/SRI-CSL/whole-program-llvm/blob/master/tutorial.md)
112+
which will produce the bitcode module `pkg-config.bc`.
113+
114+
115+
Tutorials
116+
=========
117+
118+
A gentler set of instructions on building apache in a vagrant Ubuntu 14.04 can be found
119+
[here,](https://github.com/SRI-CSL/whole-program-llvm/blob/master/doc/tutorial.md) and for Ubuntu 16.04 [here.](https://github.com/SRI-CSL/whole-program-llvm/blob/master/doc/tutorial-ubuntu-16.04.md)
92120

93121
Building a bitcode module with dragonegg
94122
========================================
@@ -102,9 +130,12 @@ Building a bitcode module with dragonegg
102130
CC=wllvm ./configure
103131
make
104132

105-
# Produces pkg-config.bc
133+
Again, this should produce the executable `pkg-config`. To extract the bitcode:
134+
106135
extract-bc pkg-config
107136

137+
which will produce the bitcode module `pkg-config.bc`.
138+
108139

109140
Building bitcode archive
110141
========================
@@ -119,17 +150,30 @@ Building bitcode archive
119150
# Produces src/LinearMath/libLinearMath.bca
120151
extract-bc src/LinearMath/libLinearMath.a
121152

153+
Note that by default extracting bitcode from an archive produces
154+
an archive of bitcode. You can also extract the bitcode directly into a module.
155+
156+
extract-bc -b src/LinearMath/libLinearMath.a
157+
158+
produces `src/LinearMath/libLinearMath.a.bc`.
159+
160+
122161

123162
Building an Operating System
124163
============================
125164

126-
To see how to build freeBSD 10.0 from scratch check out this
127-
[guide.](../master/README-freeBSD.md)
165+
To see how to build freeBSD 10.0 from scratch check out this
166+
[guide.](https://github.com/SRI-CSL/whole-program-llvm/blob/master/doc/tutorial-freeBSD.md)
128167

129168

130169
Configuring without building bitcode
131170
================================
132171

172+
Sometimes it is necessary to disable the production of bitcode.
173+
Typically this is during configuration, where the production
174+
of unexpected files can confuse the configure script. For this
175+
we have a flag `WLLVM_CONFIGURE_ONLY` which can be used as
176+
follows:
133177

134178
WLLVM_CONFIGURE_ONLY=1 CC=wllvm ./configure
135179
CC=wllvm make
@@ -149,9 +193,11 @@ Building a bitcode archive then extracting the bitcode
149193
extract-bc libjansson.a
150194
llvm-ar x libjansson.bca
151195
ls -la
152-
196+
153197

154198

199+
200+
155201
Debugging
156202
=========
157203

@@ -183,4 +229,4 @@ it might point out what is wrong.
183229
License
184230
=======
185231

186-
WLLVM is released under the MIT license. See the file `LICENSE` for details.
232+
WLLVM is released under the MIT license. See the file `LICENSE` for [details.](https://github.com/SRI-CSL/whole-program-llvm/blob/master/LICENSE)

‎README.rst

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
Introduction to WLLVM
2+
=====================
3+
4+
This project, WLLVM, provides tools for building whole-program (or
5+
whole-library) LLVM bitcode files from an unmodified C or C++
6+
source package. It currently runs on `*nix` platforms such as Linux,
7+
FreeBSD, and Mac OS X.
8+
9+
WLLVM provides python-based compiler wrappers that work in two
10+
steps. The wrappers first invoke the compiler as normal. Then, for
11+
each object file, they call a bitcode compiler to produce LLVM
12+
bitcode. The wrappers also store the location of the generated bitcode
13+
file in a dedicated section of the object file. When object files are
14+
linked together, the contents of the dedicated sections are
15+
concatenated (so we don't lose the locations of any of the constituent
16+
bitcode files). After the build completes, one can use an WLLVM
17+
utility to read the contents of the dedicated section and link all of
18+
the bitcode into a single whole-program bitcode file. This utility
19+
works for both executable and native libraries.
20+
21+
This two-phase build process is necessary to be a drop-in replacement
22+
for ``gcc`` or ``g++`` in any build system. Using the LTO framework in gcc
23+
and the gold linker plugin works in many cases, but fails in the
24+
presence of static libraries in builds. WLLVM's approach has the
25+
distinct advantage of generating working binaries, in case some part
26+
of a build process requires that.
27+
28+
WLLVM works with either ``clang`` or the ``gcc dragonegg`` plugin.
29+
30+
31+
Usage
32+
-----
33+
34+
WLLVM includes two python executables: ``wllvm`` for compiling C code
35+
and ``wllvm++`` for C++, and an auxiliary tool ``extract-bc``.
36+
37+
Three environment variables must be set to use these wrappers:
38+
39+
* ``LLVM_COMPILER`` should be set to either ``dragonegg`` or ``clang``.
40+
* ``LLVM_GCC_PREFIX`` should be set to the prefix for the version of gcc that should
41+
be used with dragonegg. This can be empty if there is no prefix. This variable is
42+
not used if ``$LLVM_COMPILER == clang``.
43+
* ``LLVM_DRAGONEGG_PLUGIN`` should be the full path to the dragonegg plugin. This
44+
variable is not used if ``$LLVM_COMPILER == clang``.
45+
46+
Once the environment is set up, just use ``wllvm`` and ``wllvm++`` as your C
47+
and C++ compilers, respectively.
48+
49+
50+
In addition to the above environment variables the following can be optionally used:
51+
52+
* ``LLVM_CC_NAME`` can be set if your clang compiler is not called ``clang`` but
53+
something like ``clang-3.7``. Similarly ``LLVM_CXX_NAME`` can be used to describe
54+
what the C++ compiler is called. Note that in these sorts of cases, the environment
55+
variable ``LLVM_COMPILER`` should still be set to ``clang`` not ``clang-3.7`` etc.
56+
We also pay attention to the environment variables ``LLVM_LINK_NAME`` and ``LLVM_AR_NAME`` in an
57+
analagous way, since they too get adorned with suffixes in various Linux distributions.
58+
59+
* ``LLVM_COMPILER_PATH`` can be set to the absolute path to the folder that
60+
contains the compiler and other LLVM tools such as ``llvm-link`` to be used.
61+
This prevents searching for the compiler in your PATH environment variable.
62+
This can be useful if you have different versions of clang on your system
63+
and you want to easily switch compilers without tinkering with your PATH
64+
variable.
65+
Example ``LLVM_COMPILER_PATH=/home/user/llvm_and_clang/Debug+Asserts/bin``.
66+
67+
* ``WLLVM_CONFIGURE_ONLY`` can be set to anything. If it is set, ``wllvm``
68+
and ``wllvm++`` behave like a normal C or C++ compiler. They do not
69+
produce bitcode. Setting ``WLLVM_CONFIGURE_ONLY`` may prevent
70+
configuration errors caused by the unexpected production of hidden
71+
bitcode files.
72+
73+
74+
Documentation
75+
-------------
76+
77+
More detailed documentation as well as some tutorials can be found
78+
here:
79+
80+
https://github.com/SRI-CSL/whole-program-llvm

‎README-freeBSD.md renamed to ‎doc/tutorial-freeBSD.md

File renamed without changes.

0 commit comments

Comments
 (0)