+Instructions to build Bacula using the MinGW32 on Linux
+=======================================================
-This file documents building the Bacula Win32 FD using the cross-tool
-on a Linux (possibly other Unix) system.
+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 Fedora Core 5 and SuSE so those should definitely work. But there
+shouldn't be any issues on other Linux distributions.
-The basic directory structure you need to have is:
- bacula top level directory -- any name
- bacula-source 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 and CentOS. 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 Win32 FD is built.
- compat Bacula win32 emulation lib for Unix calls
-
- dekpgs-win32
- pthreads The POSIX pthreads library (third party)
- zlib The zlib library (third party)
- wx The wxWidgets library (third party)
- openssl The OpenSSL library (third party)
-
- cross-tools Cross compliation tools (gcc, g++, mingw, ...)
- vss A copy of the Windows VSS directory
- inc
- ...
- lib
- ...
-
-depkgs-win32 is released in a separate .tar.gz file that contains the
-source for the above mentioned libraries needed to build the
-Win32 Bacula. It can be found in the Source Forge Bacula project
-release section. Docs is released as a separate tar file, which is
-created from the bacula CVS docs project (module).
-
-cross-tools is a directory that you create. There is a script, described
-below, that will download all the necessary files and build them. You need
-only run that script once, unless we move to a new version of the tools.
-In addition, you must download the Microsoft VSS libraries, install them
-on a Windows system. We are not allowed to distribute those files so you
-must do it yourself. Normally the files will be installed in:
-
- c:/Program Files/VSSSDK71
-
-you need only copy everything under that directory into cross-tools/vss.
-Note, only the inc and lib directories are needed (and I'm not even sure
-that the lib directory is needed).
-
-Now, once you have the directory structure as defined above, you do
-the following once:
-
- cd bacula/bacula-source
- ./configure (any standard set of config options the exact ones
- are not important).
- cd src/win32
- ./build-win32-cross-tools
-
-The above only needs to be done once unless we change the cross-tools
-version. In general, you can run the script multiple times with no
-problem. For it to work, you must have a valid gcc compiler installed on
-your system as well as wget and texinfo. There may be other dependencies.
-
-After building the cross-tools, you can proceed to build the depkgs-win32
-packages, which must use the cross-tools compiler.
-
- cd depkgs-win32
- ./build-mingw32
-
-The above only needs to be done once as well as long as the cross-tools or
-depkgs-win32 versions do not change.
-
-Finally, to build the Win32 Bacula FD and bconsole, do the following:
-
- cd bacula-source/src/win32
+ win32 Main directory where Windows version is built.
+
+ 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 --
+ include |
+ lib |
+ man | Created by script
+ nsis |-- .../bacula/src/win32/build-depkgs-mingw32
+ scons |
+ share |
+ src |
+ ssl --
+ vss
+ inc A copy of the Windows VSS/inc directory
+
+ 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 |
+ source --
+
+
+One-time Setup
+==============
+
+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. It is referred to as bacula-top in the
+diagram located in README.win32. It will be signified in this file as ...
+
+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
+
+Download and build the cross compiler tools
+ ./build-win32-cross-tools
+
+Download and build the 3rd party 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:
+
+http://www.microsoft.com/downloads/details.aspx?FamilyID=0b4f56e4-0ccc-4626-826a-ed2c4c95c871&DisplayLang=en
+
+If that link doesn't work then go to http://www.microsoft.com and search for
+
+ "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\Microsoft\VSSSDK72
+
+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
+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:
+
+ gcc
+ g++
+ wget
+ texinfo
+ bison
+ flex
+
+and possibly other packages.
+
+
+Building
+========
+
+Finally, to build the Microsoft Windows version of Bacula, do the following:
+
+ cd .../bacula/src/win32
+ make
+
+If all goes well, you will end with all the executables in the
+.../bacula/src/win32/release directory.
+
+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
+ svn update
+ cd src/win32
make
-if all goes well, you will end with bacula-fd.exe, bconsole.exe,
-pthreadGCE.dll, and mingwm10.dll in the current directory.
+The installer is now built as part of the default rule when you
+say "make" in the src/win32 directory.
+
+
+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.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.
-Items to be done:
-- Get VSS builds to work
-- Complete the automated build of depkgs-win32
-- Modify the Win32 build to turn on OpenSSL
-- Build the other Win32 tools (bsmtp, wx-console, tools, ...)
+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.