-This file documents building Bacula for Microsoft Windows using the
-cross-compiler tools on a Linux (or possibly another Unix) system.
+Instructions to build Bacula using the MinGW32 on Linux
+=======================================================
-The basic directory structure you need to have is:
+This file documents the tools (scripts) we use for building Bacula for
+Microsoft Windows using the cross-compiler tools on a Linux system. We
+use Ubuntu 8.04 so building on that system should definitely work. But there
+shouldn't be any issues on other Linux distributions.
- bacula-top top level directory -- any name
- bacula top level Bacula source directory -- any name
+We don't officially support this script, but it is what we use, and it should
+build on any Linux machine if you carefully follow the instructions and have
+all the prerequisite programs loaded on your machine.
+
+It has also been tested on other systems such as FreeBSD, CentOS, Fedora, and SUSE.
+We expect that there may be problems on systems other than Linux where you
+are pretty much on your own. However, we will try to provide responses to
+your questions on the bacula-devel list, but we can't guarantee anything.
+
+Directory Structure
+=====================
+The new directory structure is:
+
+ bacula-top Top level directory -- any name
+ bacula Top level Bacula source directory -- any name
src
- win32 main directory where the Windows version is built.
+ win32 Main directory where Windows version is built.
- dekpgs-mingw32 3rd Party Dependencies
- bin --
+ docs Top level Bacula documentation directory
+
+ depkgs-mingw32 (MinGW32) 3rd Party Dependencies for MinGW32 build
+or
+ depkgs-msvc (MS VC++) 3rd Party Dependencies for Microsoft VC++ build.
+ bin -- NOTE! depkgs-msvc is no longer suppored
include |
lib |
man | Created by script
- nsis |-- ..../bacula/src/win32/build-dependencies
- scons |
+ nsis |-- .../bacula/src/win32/build-depkgs-mingw32
+ scons |
share |
src |
ssl --
vss
inc A copy of the Windows VSS/inc directory
- cross-tools Cross compilation tools (gcc, g++, mingw, ...)
+ cross-tools (MinGW32) Cross compilation tools (gcc, g++, mingw32, ...)
binutils-mingw32 --
gcc-mingw32 | Created by script
- mingw32 |-- ..../bacula/src/win32/build-win32-cross-tools
- mingw-utils |
+ mingw32 |-- .../bacula/src/win32/build-win32-cross-tools
+ mingw-utils |
source --
+
One-time Setup
==============
-If you're reading this file you've probably already enlisted in the CVS tree or
+If you're reading this file you've probably already enlisted in the SVN tree or
extracted the contents of the source tar. If not you need to do that first.
+You also need to download one of the doc tar balls and extract to your
+top level Bacula directory.
+
+The extracted doc directory name will be bacula-docs-version where version
+is the version number. The directory must be renamed to docs (ie remove
+the leading bacula- and the -version portion of the name).
+
+Note, a number of packages must be installed to build the cross-tools
+and the depkgs files. Most are rather standard such as gcc, g++,
+make, ... However a few that you may not have are:
+
+ texinfo
+ flex
+ bison
+ patch (Debian)
+ m4
+ postgresql (at least client)
+ mysql (at least client)
+ SQLite3 (from depkgs or as package)
+ readline (readlineN-dev on Debian)
+ ...
+
+NB: On Debian, I had to remove /usr/bin/lorder for
+postresql to build correctly.
+
Once the source is on your system, change to the win32 directory
- cd ..../bacula/src/win32
+ cd .../bacula/src/win32
Download and build the cross compiler tools
./build-win32-cross-tools
Download and build the 3rd party dependencies
- ./build-dependencies
+ ./build-depkgs-mingw32
+
+Note, that during the build process you will see a moderate amount of
+output. If something fails, it is probably because you don't have one
+of the build dependencies (hopefully all mentioned above) loaded on your
+system. To find out what is going wrong, do the following:
+
+ cd .../depkgs-mingw32/src/<package-name>
+
+where <package-name> is where the package is unpacked and built. Normally
+it is relatively obvious when looking at the src directory.
+
+In that directory, you should find a make.log, which has the full details
+of the compiles, links, and installs done for that package.
+
+Note, if you are building on a 64 bit machine, please know that
+the build for the depkgs-mingw32/scons puts the python scons libraries
+in depkgs-mingw32/scons/lib64 but when running scons it looks for the
+libs in depkgs-mingw32/scons/lib. So adding symlink from
+depkgs-mingw32/scons/lib64 to depkgs-mingw32/scons/lib will fix the
+problem.
You need the header files from the Microsoft VSS SDK. Unfortunately the SDK
-can only be downloaded and installed on a Windows system. You can find it on
-Microsoft's web-site at:
+can only be downloaded and installed on a Windows system. We do not have
+the right to distribute it, so you must download it yourself.
+You can find it on Microsoft's web-site at:
http://www.microsoft.com/downloads/details.aspx?FamilyID=0b4f56e4-0ccc-4626-826a-ed2c4c95c871&DisplayLang=en
"download volume shadow copy service sdk"
+we are currently using version 7.2 released 8/3/2005.
+
Normally the files will be installed in:
- c:/Program Files/VSSSDK72
+ c:\Program Files\Microsoft\VSSSDK72
-You only need to copy everything under the c:/Program Files/VSSSDK72/inc
-directory into ..../depkgs-mingw32/vss/inc.
+You only need to copy everything under the c:\Program Files\Microsoft\VSSSDK72\inc
+directory into .../depkgs-mingw32/vss/inc. In doing so, please ensure that
+the case in maintained on the directory and filenames -- some contain uppercase
+characters !!!
-The above only needs to be done once unless we change the cross-tools
+The above only needs to be done once unless we change the cross-tools
or the dependencies versions. In general, you can run the script multiple
times with no problem. For it to work, you must have at a minimum the
following:
wget
texinfo
bison
- man2html
+ flex
+ python
+ unzip
+ tar
and possibly other packages.
+
Building
========
Finally, to build the Microsoft Windows version of Bacula, do the following:
- cd ..../bacula/src/win32
- make
+ cd .../bacula/src/win32
+ make
If all goes well, you will end with all the executables in the
-..../bacula/src/win32/release directory.
+.../bacula/src/win32/release directory, and the installer binary
+containing everything will be named winbacula-xx.yy.zz.exe where
+xx.yy.zz is the Bacula version you are building.
If you have an older build environment, you might do the following
to ensure that you pick up all the new Win32 changes:
- cd <bacula>
- make clean
- cd src/win32
- make clean
- cd ../..
- cvs update
- cd src/win32
- make
-
-If one of the patches change in src/win32/patches, you shouldn't
-need to update the cross-tools or dependencies for it to build.
-You can install new patches by doing the following (we assume the patch
-in question is for openssl):
-
- cd <top-level>
- # delete openssl
- rm -rf depkgs-mingw32/src/openssl-0.9.8b
- cd <bacula-source>/src/win32
- # Call script to reload/rebuild openssl
- ./build-dependencies openssl
-
-
-Structure of the new Win32 build environment (from Robert):
-
-I've redesigned the minw32 build somewhat, much thanks to Kern and Howard
-for the initial work.
-
-For doing a build it is very simple, type make in src/win32 or whichever
-subdirectory you are working on. For those maintaining it, its a little
-more complicated :-)
-
-Here is some documentation for the maintainers.
-
-The basic strategy is each makefile in the various subdirectories includes
+ cd .../bacula
+ make clean
+ svn update
+ cd src/win32
+ make
+
+
+Updating the 3rd party package patches
+======================================
+
+If one of the patches changes in .../bacula/src/win32/patches, you will
+need to update the corresponding dependency. You can install new patches
+by doing the following (we assume the patch in question is for openssl).
+
+ cd .../bacula/src/win32
+ ./build-depkgs-mingw32 -C openssl
+
+NOTE: The -C means clobber. Any local changes to the source code in
+ the .../depkgs-mingw32/src directory will be lost. The source
+ will be reextracted from the archive and the current patches
+ will be applied.
+
+
+Adding a new global function or global data
+===========================================
+
+bacula.dll
+----------
+
+The code from the following directories is built into bacula.dll:
+
+ .../bacula/src/lib
+ .../bacula/src/libfind
+ .../bacula/src/win32/compat
+
+A new function or data variable which must be accessed from outside
+of bacula.dll requires special treatment. It must be specifically
+exported.
+
+New data variables are exported by adding the macro DLL_IMP_EXP to
+the variable declaration in the header file. All exported variables
+must be declared in a header file and MUST NOT be declared in a
+source file referencing the variable. Example, src/lib/runscript.h:
+
+extern DLL_IMP_EXP bool (*console_command)(JCR *jcr, const char *cmd);
+
+or src/jcr.h
+
+extern int DLL_IMP_EXP num_jobs_run;
+extern DLL_IMP_EXP dlist * last_jobs;
+...
+
+
+Exporting functions is now more or less automated. If you find that
+a function name has been added, changed, or an argument modified,
+simply do the following:
+
+ cd .../bacula/src/win32/dll
+ make (to build the .o files, note the link will fail)
+ ./make_def >bacula.def
+
+This should rebuild the bacula.def file, but it uses relative paths
+and assumes you have the directory structure noted above. If you
+are using something different, you can set the NM variable at the
+top of the make_def file to use an absolute path to the correct
+directory.
+
+===== manual changing of bacula.def no longer necessary =====
+If you want to do it manually, please see below:
+Exporting a function requires a bit more work. You must determine the
+C++ mangled name of the new function.
+
+ strings .../bacula/src/win32/dll/<file>.o | grep <symbol>
+
+Note, strings often will not show the desired symbol. In that case,
+use:
+
+ nm .../bacula/src/win32/dll/<file>.o
+
+Replace <file> with the base part of the name of the source code file
+which contains the new function. Replace <symbol> with the name of
+the new function. Remove the leading underscore and place the result
+in the file
+
+ .../bacula/src/win32/dll/bacula.def
+=== end manual changing of bacula.def ==========
+
+If you add a new file, you will need to specify its name in
+
+ .../bacula/src/win32/dll/Makefile
+and
+ .../bacula/src/win32/libbac/Makefile
+
+bacula_cats.dll
+---------------
+
+The code from the .../bacula/src/cats directory is built into database
+provider specific libraries of the form cats_<db>.dll.
+
+The database specific portion <db> is mysql for MySQL, pgsql for
+PostgreSQL, sqlite for SQLite, and bdb for the built-in Bacula database.
+
+During installation of the Director, one of the database libraries is
+copied to the system and renamed bacula_cats.dll.
+
+A new function or data variable which must be accessed from outside
+of bacula_cats.dll requires special treatment. It must be specifically
+exported.
+
+New data variables are exported by placing their name in the file
+.../bacula/src/win32/cats/bacula_cats.def.
+
+As with the bacula.def file above, this is now more or less automated.
+When the link dies, simply do the following:
+
+ cd .../bacula/src/win32
+ make (to build the .o files, note the link will fail)
+ cd cats
+ ./make_def >bacula_cats.def
+
+This should rebuild the bacula_cats.def file. Note, if you have
+changed any data entry points, you will need to modify the make_def
+script -- it should be rather obvious.
+
+
+===== manual changing of bacula_cats.def no longer necessary =====
+Exporting a function requires a bit more work. You must determine the
+C++ mangled name of the new function.
+
+ strings .../bacula/src/win32/cats/cats_*/<file>.o | grep <symbol>
+
+Note, strings often will not show the desired symbol. In that case,
+use:
+
+ nm .../bacula/src/win32/dll/<file>.o
+
+Replace <file> with the base part of the name of the source code file
+which contains the new function. Replace <symbol> with the name of
+the new function. Remove the leading underscore and place the result
+in the .../bacula/src/win32/cats/bacula_cats.def file.
+=== end manual changing of bacula_cats.def ==========
+
+
+Running gdb on the Win32 files
+==================================================
+You can use the mingw32 gdb to debug Bacula on Win32 by downloading
+it from Source Forge:
+
+http://sourceforge.net/project/showfiles.php?group_id=2435&package_id=20507
+
+Download one of their .exe versions, which is an installer that you
+can run on Win32 to install gdb. This gdb is built with mingw32 so will
+run independently of any cygwin installation. Note, not all the releases
+come with an installer. I had to go back 3 or 4 versions to find it. Otherwise
+you can download the source and build it. Thanks to Eric Bollengier for
+this tip.
+
+
+Structure of the MinGW32 build environment
+==========================================
+
+The basic strategy is each Makefile in the various subdirectories includes
Makefile.inc, defines variables and rules specific to what is being built,
then includes Makefile.rules which defines all the rules.
-
+
Makefile.inc defines the locations of all the dependencies and the compiler
-and linker flags. It is automatically created from Makefile.inc.cross. Any
-changes must be made to Makefile.inc.cross not Makefile.inc or they will be
-overwritten the next time Makefile.inc.cross is updated. There is also a
-file called Makefile.inc.native. This file is used for MinGW32 running on
-Windows. However at this time it probably isn't useful to anyone but me
-since the locations aren't updated automatically.
-
+and linker flags. It is automatically created from Makefile.inc.in. Any
+changes must be made to Makefile.inc.in not Makefile.inc or they will be
+overwritten the next time Makefile.inc.in is updated.
+
Makefile.rules defines a bunch of macros to simplify building. It also
includes all the basic rules for building objects, GUI and console
executables, etc.
-
+
Makefile.template is a template for creating new Makefiles, if you are
creating a new directory, copy Makefile.template to Makefile in that
directory and edit to suit.