Making (building) Boomerang
You can make boomerang in the following forms:
- As a console tool with many command line options, using a large log file for debugging. This can be built under Unix (Linux, Solaris, Mac OS X; others may work with effort) or Windows (compiled with Microsoft Visual Studio .NET 2003 or 2005, including the currently freely downloadable express edition, or with Cygwin or MinGW).
- As a QT4 Open Source GUI tool; this is the latest in a long line of GUIs, but does not yet have support for most command line switches etc as yet. See QuantumG's Chronicle of a Decompilation for some clues on what it looks like and what you can do with it. This can in theory be built in any environment supported by the QT4 open source toolkit, including Visual Studio with some mucking about (see below). Under Windows, it can be built with Visual Studio 2003/5 or with MinGW. The GUI has the decompiler engine linked in; it does not need the console tool (boomerang.exe) to run, however the Makefiles for MinGW assume that all the Boomerang .obj files are already created and are up to date.
- There was a native Windows-only GUI version, deprecated as of September 2006.
This was an older version of the GUI, but it had support for
most command line switches. Beware that this version is not tested any more, so problems
will certainly crop up. This version could only be built in Visual Studio. The solution and project files
have been renamed from boomerang
.sln/vcproj to boomerang-win .sln/vcproj, in case there are people wanting to continue work on this version. NOTE: the targets should be renamed to boomerang-win.exe (or similar), and there are known issues with the generating of code in Clusters (current code will generate segfaults when you attempt to view the C output).
To make the Boomerang console version, you need the following tools:
- On Linux/Solaris/Cygwin/MinGW/OS X:
- gcc version 3.1 or later (3.0 should work.) There have been reports of problems with gcc 4.X, though 4.0.2 is known to work. Because of the strstream / stringstream issue, it's not worth attempting to compile it on older gcc versions.
- For Debian, you can sudo apt-get install libgc-dev.
- On Windows: one of the following compilers/environments:
- MSVC 7.0 or later (Visual Studio .NET 2002/2003 or Visual Studio 2005 or later) compiles and works OK; see notes below. Use the solution file boomerang.sln (.NET 2003) or boomerang_vs2002.sln (.NET 2002) or boomerang_vs2005 (VS2005) in the top level boomerang directory.
- MSVC6 and earlier are not really feasible. There are some old .dsp and .dsw files in win32make/ for the truly adventurous (thanks, Robert!).
- Cygwin (a Unix-like
environment for Windows): configures, compiles and runs but there is an issue
with the MachO code. For now, the file loader/MachOBinaryFile.cpp will not compile,
so the MachO loader is disabled when the host environment is Cygwin.
In other words, under Cygwin, you can't decompile MachO binaries, but you can decompile
any others, including ELF PowerPC binaries. As of September 2006, there is a workaround for a mysterious problem
whereby it compiles and cygchecks OK, but exits immediately with no error. In the Makefile, comment out
the reference to xmlprogparser.o (it's conveniently at the end of the line now).
Note that the functional test code seems to run rather slowly under Cygwin; it runs much faster under MinGW. The reason for this is unclear.
At one stage I could not get the gc and expat libraries booked into Boomerang (as gc.dll and libexpat.dll) to work. It would link, but the resultant binary would not run. If you have trouble making either gc or expat (I can't seem to make expat any more myself), you could use these files (350KB). Move libexpat.* to /usr/lib, and move libgc.a to lib/ . (Moving all to lib/ would probably also work).
- MinGW:
(Another Unix-like environment for Windows.) Boomerang makes
successfully on this platform now. The only difference is that the functional test scripts
(functest.sh and testOne.sh) have to be run as
sh functest.sh <args> instead of ./functest.sh
<args>.
Use these commands to copy the required libraries to the right directory for MinGW:
cp gc.dll lib/libgc.dll
cp libexpat.dll lib
Use the MSYS shell to run the configure script, and make as usual. You can download the msysDTK (Developer's ToolKit) to give you ssh and some other stuff that you don't need. Be sure not to use the ssh that comes with Cygwin; it appears to work but doesn't play ball with cvs. Remember to set the CVS_RSH environment variable; set it in ~/.profile (not ~/.bash_profile or ~/.bashrc for some reason), or set the environment variable in Windows (System control panel, advanced tab). Point it to /bin/ssh where the MinGW ssh should live. It is possible to make cppunit, and "make test" should pass all tests that the Linux version does (note that unit tests are no longer maintained properly). Two exceptions are the two global3 tests. Boomerang emits correct code, but the MinGW compiler, which relies on some Microsoft DLLs, does not handle the GCC form for long long integers. The binary compiled under MinGW needs no special libraries; the version compiled with Cygwin requires cygwin1.dll.
Thanks, Luke! - For all Visual Studio compilations, you need a manual change since you can't run the configure script:
- Rename include/config.h.win to include/config.h
- CVS, obviously, or a GUI replacement such as
Tortoise CVS or WinCVS.
(WinCVS doesn't seem to work in "developer" mode, but should work OK in anonymous login mode).
If you use command line CVS, don't forget to set CVS_RSH=/bin/ssh (or wherever your ssh is installed to). It also implies that you need ssh installed. - The Boehm garbage collector;
see http://www.hpl.hp.com/personal/Hans_Boehm/gc/.
The standard
source code compiles fine on Linux or Cygwin; just ./configure,
make, and make install. You can compile a
version for Windows (use the same source code as for other platforms)
in the form of a DLL (put gc.dll somewhere in the path, e.g. c:\windows\system32)
or create a static library and link that to Boomerang. If the compiler
can't find gc.h and gc_config_macros.h, copy them
from the source code to Boomerang's include/ .
Similarly, if it complains that it can't find -lgc, copy
libgc.a (probably in /usr/local/lib or from the
.libs/ directory where you made it) to the Boomerang
lib/ directory. (Don't use the .la or .lo files.)
There is now a VC++.NET
project file (gcc.vcproj) to make the dll. This is for version
6.2 of the garbage collector; other versions may require minor changes to the project file.
Thanks, Robert!
Note: the Windows version of this library is booked into Boomerang as gc.dll, so there is no need to download or compile the garbage collector if you are compiling for Windows (Visual Studio, Cygwin, or MinGW). Note: Tamlin has reported that there is a bug in the Windows version of the collector that affects versions 6.4 through 6.8 inclusive, so use the provided collector or no later than 6.3. The bug has been reported as of 7/Aug/2006.
- For Unix and Linux: the libdl library (for dynamic linking with dlopen and dlsym etc).
Cygwin has this built in (though you still get a warning); Windows doesn't have it but we use a different dynamic
library mechanism.
- The eXpat XML parser WAS needed;
see http://expat.sourceforge.net/ .
The XML loading and saving code has fallen so far behind that now it is disabled, so
you don't need this unless you want to restore the xmlprogparser code and re-enable these
commands.
It's an easy install: just ./configure, make, and make install
for Unix. If you don't have root access on your host machine, then you can't do the last
step. Just copy expat.h and expat_external.h
from the lib/ directory of eXpat to Boomerang's include/
directory, and copy or link libexpat.a from the .lib/ directory
of eXpat to Boomerang's lib/
directory. The configure script will now warn you if eXpat is not
installed, or if these files aren't present.
Note: the Windows version of this library is checked into Boomerang as libexpat.dll, so there is no need to download or compile this library if you are making for Windows (Visual Studio, Cygwin, or MinGW). NOTE: you can get away without installing expat if you only want to use the console version (since XML loading and saving is disabled in the console version). In boomerang.cpp, set USE_XML to 0. - cppunit (from cppunit.sourceforge.net).
This is only needed for unit testing. You can make boomerang without
it, but has been useful in the past for development. These days there is much
more ephasis on functional testing; many of the unit tests fail at present, and
it's a pain to keep them up to date. To use cppunit, you need a symbolic link from
the include/ directory to
the cppunit include directory, e.g. ln -s
/home/user/cppunit-1.6.2/include/cppunit include . If you
forget this, ./configure
will warn about "library
'cppunit' not found". I believe that there is a version for Windows.
- bison++ and flex++ (from many places, just
search.
I found them last at http://sunsite.bilkent.edu.tr/pub/languages/c++/tools/flex++bison++/LATEST/.
You may find the author's name useful as a keyword: Coetmeur).
Note that the GNU flex/flex++ and bison tools are presently not suitable
for Boomerang; with some effort, they could be made compatible.
See also FAQ question 16.
Windows binaries for these can be found at
http://www.kohsuke.org/flex++bison++/ (thanks again, Luke!)
- The ML version of the New Jersey Machine Code Toolkit.
Note: this is a significant pain to build.
See Norman Ramsey's page, but don't
use his sources; there is a memory explosion issue. So use the source files
from
this
page.
Alternatively, you can grab a binary package of the NJMC toolkit we have created. It will only be of any use to you if you're on x86 linux.
The configure script will look for .run-sml in $PATH, /usr/share/sml-nj/bin, $HOME/install/smlnj/bin, and $HOME/install/smlnj/bin, in that order; it also looks for
sml-toolkit.x86-linux or sml-toolkit.sparc-solaris in $HOME/install, $PATH, $HOME/install/mltk and $HOME/sml-nj/install in that order.
- autoconf, only if you want to update the configuration script.
To make the QT GUI, you need all the above tools, so you might consider making the console version first and make sure it runs (with no command line switches, the Boomerang console tool just gives a version number and very brief usage). The GUI files are in the qtgui2/ directory. You will also need:
- The QT4 open source toolkit from TrollTech.
This toolit is free for use on open source projects such as Boomerang. There are versions for Windows, X11
(various Unixes including Linux) and Max OS/X. Note that the Windows version does not officially support
compilation with Visual Studio (e.g. there is no qtmain.lib generated); it is designed for MinGW only.
However, there is a Sourceforge project called Q../Free
(web page here that provides up to date patches to
allow compilation with Visual Studio. The toolkit will require some 700-1200MB of disk space, although by
deleting ruthlessly you can eventually get this down to under 100MB. The MinGW distribution from
TrollTech has release binaries already made, saving some time, but you may still need to make the debug versions
of the library files (e.g. libqmaind.a).
Note: the Visual Studio 2003 project file is set up to use the release versions of the QT toolkit, even if
Boomerang itself is being built in debug mode. This doesn't seem to work for Visual Studio 2005 (you get a
weird runtime error saying that the application was not built correctly). So the 2005 project file uses
debug QT libraries when building boomerang-gui in debug mode, and you will obviously need to build the debug
versions of the QT libraries if you are using VS 2005.
They provide a Windows start menu entry to compile the debug libraries; it takes less time if you
delete or move to elsewhere the demos/ and examples/ directories. Even with this, it took
me 25 minutes and over 1G of space.
Note: if you are compiling with Visual Studio 2005, you can use this zip file to save you a lot of work and time: qt-4.1.4-vs2005.zip . The file is about 28MB, and unzips to about 95MB. - To run the resultant GUI under Linux/Unix, you will need an X server, but virtually all Linux or Unix systems will provide one. If you are connecting remotely through ssh, you may need switches such as -Y or -X to enable X11 tunelling. The GUI can be somewhat slow over such connections.
- Make the toolkit itself and the Boomernag GUI in the command shells provided, not in an MSYS shell and do not run sh.exe. It seems that the TrollTech tools all generate reverse slashes, which are ignored by these shells. (You can use -unix with qmake, but that also seems to change the libraries that are specified etc.
- Change to the qtdir2 directory; do all the making here but return to the parent directory to actually run Boomerang.
- set QMAKESPEC=win32-g++
- Create a new makefile with qmake -o Makefile.mingw qtgui2-mingw.pro. Note that the mypthread.cpp file is a hack only needed for Unix, and not for MinGW. So it is commented out in the qtgui2-mingw.pro project file. This project file was originally created with qmake -project -o qtgui2-mingw.pro, but I don't suggest doing this again because there are many extra object files, include directories, and library commands to add to what this produces.
- Make with mingw32-make -f Makefile.mingw.Debug. You may have to get the mingw32-make tool from the MinGW website; the standard make utility in the MinGW bin/ directory is not suitable. The result should be a 42M or so file debug\qtgui2-mingw.exe. You may wish to copy this to the parent directory as boomerang-gui.exe for convenience.
- To make under Linux or Unix, substitute qtgui2-unx and Makefile.unx and do not set the QMAKESPEC environment variable.
- Make sure you use the right solution file, which will use the right project files. Use qtgui2.sln for VS 2003, qtgui2_vs2005.sln for VS 2005, and qtgui2_vs2002.sln for VS 2002.
- There are fixed paths in the files, e.g. c:\Qt\4.1.4-vs2005. Either edit the project files with a text editor, or use the appropriate facilities in Visual Studio. Don't forget to update the Release paths as well as the Debug ones.
- I found that I had to hunt down some files like MSVCP80D.DLL and copy them to the WINDOWS\system32 directory. There were 6 in total (3 debug and 3 release). These are used by the QtCore4[d].dll library, not directly by Boomerang.
Known Make Problems
With the Windows version, sometimes the linker complains that __alloca_free_ptr is multiply defined. The function should be declared static (so that it doesn't appear in the linker's symbol table). The work around is to simply add the keyword "static" before "int __alloca_free_ptr(char ....", e.g. in the file db/sslparser.cpp:/* ALLOCA SIMULATION */
/* __HAVE_NO_ALLOCA */
#ifdef __HAVE_NO_ALLOCA
static int __alloca_free_ptr(char *ptr,char *ref)
{if(ptr!=ref) free(ptr);
return 0;}
The linker warns about "...statement not supported for the target platform; ignored" when linking BinaryFile.lib. It appears that this is because there are no functions officially exported from BinaryFile.dll.
Under Unix (Linux/Solaris/OS X), if you try to make one of the loader objects that needs
special includes, e.g. make loader/MachOBinaryFile.o
it won't make correctly. Change to the loader/ directory and use
make MachOBinaryFile.o
The configuration script under Cygwin complains incorrectly about the lack of libdl.a; just ignore this message.
Some functional tests (./functest.sh) may fail because the Windows file system has a coarse time stamp. At present, we use `ls -rt output/$2/*.c` to get the names of the generated source files in the order that they were created. The workaround is to manually recompile tests that fail when the output appears to be correct.
Solaris seems to have a problem with the SSL parser. I can work around this by remaking sslparser.cpp (I have bison++ 1.27-7, I don't know if this is relevant). It also seems to have a problem recently with make test where it seems to forget what cd - means. The workaround is simply to enter ./bigtest manually.
Under Mac OS X, it is probably not worth attempting to make Boomerang with OS X version 10.1 (Puma) or earlier (Cheetah). Until the paths get fixed, it is necessary at present to make a soft link from ../lib/ to lib/. There are some known problems with Boomerang under OS/X. The config.guess and config.sub files were over 5 years old and have been updated recently; this may help with configuring less common systems such as OpenPower.
Dependencies are now generated automatically with make depend. This uses the makedepend tool. You presumably will not need this.
Some users have experienced the situation where after a successful make, Boomerang segfaults for any input program. Question 15 of the FAQ offers a possible solution. This may be fixed now that libraries are accessed with a relative path.
Performance
For reasons unknown, Boomerang seems to run about 3 times as fast on Linux as it does on Windows under MinGW, and about 4 times as fast on Linux as on native Windows compiled with Visual Studio. This is with unoptimised code (gcc -O0 and debug build for Visual Studio), on the same machine. Perhaps this has something to with the performance of the garbage collector under Windows.Last modified: 28/Oct/2012: added "sudo" to "apt-get"; added more toolkit search paths; added qt-4.1.4-vs2005.zip; more on VS2005 building
