FAQ - Contents

How do I invoke the Proteus generated jar files
First compile all the individual files to bitcode files (.bc)
java -Xmx1024m program.jar Proteus arguments -- Program arguments
How to produce a single ll file from multiple sources

From a command prompt with llvm-gcc and llvm in your path type the following

First compile all the individual files to bitcode files (.bc)
llvm-g++ -c --emit-llvm [Normal options] part1.cc -o part1.bc llvm-g++ -c --emit-llvm [Normal options] part2.cc -o part2.bc llvm-g++ -c --emit-llvm [Normal options] part3.cc -o part3.bc
Combine these together using llvm-ld (Note that disabling optimisations is not mandatory but allows you the ability to play with the optimisations freely).
llvm-ld -disable-opt -o combined part1.bc part2.bc part3.bc
Run any optimisations that you want and produce ll output (-disable-inlining reduces the size of the Java classes which gives a performance benefit)
opt -S -disable-inlining -O3 -std-compile-opts -std-link-opts combined.bc -o combined-optimized.ll

Then use combined-optimized.ll with Proteus

How do I know whether the combined file will work

This is very similar to the process above but produces a native executable at the end

First compile all the individual files to bitcode files (.bc)
llvm-g++ -c --emit-llvm [Normal options] part1.cc -o part1.bc llvm-g++ -c --emit-llvm [Normal options] part2.cc -o part2.bc llvm-g++ -c --emit-llvm [Normal options] part3.cc -o part3.bc
Combine these together using llvm-ld (Note that disabling optimisations is not mandatory but allows you the ability to play with the optimisations freely).
llvm-ld -disable-opt -o combined part1.bc part2.bc part3.bc
Run the optimisations on the combined file
opt -O3 -std-compile-opts -std-link-opts combined.bc -o combined-optimized.bc
Compile to executable
llc combined-optimized.bc -o combined-optimized.s g++ combined-optimized.bc -o combined-optimized.exe [Any libraries that need to be included ]
I have a MakeFile - how can I use this to help build the ll file

In essence a MakeFile that uses gcc for compilation will be very suitable for the basis of building an ll file. Obviously, creating a makefile that replaces gcc and g++ with llvm-gcc and llvm-g++ and adds additional options is a maintainable strategy to take.

A strategy that is simple and straightforward to implement for a one-off conversion is the following.

Capture the actions of the MakeFile to text file. It is important that this is a complete build
make clean
If using a configure script run that as well
./configure [configure options]
Capture the actions of the MakeFile to text file.
make 2> build-ll.txt
Open the build-ll.txt in a text editor e.g. Notepad++/gedit/nano etc. Search and replace instances of the compilation lines such that
g++ [compile options] mycomponent.cc -o mycomponent.o
becomes
llvm-g++ -c --emit-llvm [compile options] mycomponent.cc -o mycomponent.bc

Lines which combine use ar or ranlib files may be removed and replaced with a final llvm-ld to link all the bc files together as shown in the above examples.

Can I still use -O3 or other options when I compile.

Yes, but looking at performance tips may suggest that additional options may be advisable or disregarded

Why are all the function names so strange?

By default Proteus hashes function names that are not provided to 'F<line number in ll file>'. This can be disabled using the configuration parameter -force-name true

Also, C++ programs support the same function being declared on multiple classes so the function name is not unique. Also, C++ supports overloading of functions i.e. the same function declared multiple times with different arguments. The names of C++ functions are mangled to support both of these features.

Proteus supports the 'renaming' of functions so they can be given a specific name, this is useful for functions that you have implemented in order to ensure that changes in the ll file do not affect the use of these functions. For more information see configuring proteus.

How do I know whether a program will compile with Proteus.

Some information on the limitations of Proteus are listed here. However, it is possible that it is incomplete.

One benefit of Proteus is that there is an intermediate source generation phase. Using the generated sources it is possible to copy and use them as a basis as an alternate implementation. For example, if a function calls a C/C++ function that has not implemented then a compilation error will result. This function source file can be copied and then provided with a alternate implementation which does not make this call. To use your own functions with proteus, is described here.