1 Instructions to build Bacula using the MinGW32 on Linux
2 =======================================================
4 This file documents the tools (scripts) we use for building Bacula for
5 Microsoft Windows using the cross-compiler tools on a Linux system. We
6 use Ubuntu 8.04 so building on that system should definitely work. But there
7 shouldn't be any issues on other Linux distributions.
9 We don't officially support this script, but it is what we use, and it should
10 build on any Linux machine if you carefully follow the instructions and have
11 all the prerequisite programs loaded on your machine.
13 It has also been tested on other systems such as FreeBSD, CentOS, Fedora, and SUSE.
14 We expect that there may be problems on systems other than Linux where you
15 are pretty much on your own. However, we will try to provide responses to
16 your questions on the bacula-devel list, but we can't guarantee anything.
20 The new directory structure is:
22 bacula-top Top level directory -- any name
23 bacula Top level Bacula source directory -- any name
25 win32 Main directory where Windows version is built.
27 docs Top level Bacula documentation directory
29 depkgs-mingw32 (MinGW32) 3rd Party Dependencies for MinGW32 build
31 depkgs-msvc (MS VC++) 3rd Party Dependencies for Microsoft VC++ build.
32 bin -- NOTE! depkgs-msvc is no longer suppored
35 man | Created by script
36 nsis |-- .../bacula/src/win32/build-depkgs-mingw32
42 inc A copy of the Windows VSS/inc directory
44 cross-tools (MinGW32) Cross compilation tools (gcc, g++, mingw32, ...)
46 gcc-mingw32 | Created by script
47 mingw32 |-- .../bacula/src/win32/build-win32-cross-tools
55 If you're reading this file you've probably already enlisted in the SVN tree or
56 extracted the contents of the source tar. If not you need to do that first.
58 You also need to download one of the doc tar balls and extract to your
59 top level Bacula directory.
61 The extracted doc directory name will be bacula-docs-version where version
62 is the version number. The directory must be renamed to docs (ie remove
63 the leading bacula- and the -version portion of the name).
65 Note, a number of packages must be installed to build the cross-tools
66 and the depkgs files. Most are rather standard such as gcc, g++,
67 make, ... However a few that you may not have are:
74 postgresql (at least client)
75 mysql (at least client)
76 SQLite3 (from depkgs or as package)
77 readline (readlineN-dev on Debian)
80 NB: On Debian, I had to remove /usr/bin/lorder for
81 postresql to build correctly.
83 Once the source is on your system, change to the win32 directory
84 cd .../bacula/src/win32
86 Download and build the cross compiler tools
87 ./build-win32-cross-tools
89 Download and build the 3rd party dependencies
90 ./build-depkgs-mingw32
92 Note, that during the build process you will see a moderate amount of
93 output. If something fails, it is probably because you don't have one
94 of the build dependencies (hopefully all mentioned above) loaded on your
95 system. To find out what is going wrong, do the following:
97 cd .../depkgs-mingw32/src/<package-name>
99 where <package-name> is where the package is unpacked and built. Normally
100 it is relatively obvious when looking at the src directory.
102 In that directory, you should find a make.log, which has the full details
103 of the compiles, links, and installs done for that package.
105 Note, if you are building on a 64 bit machine, please know that
106 the build for the depkgs-mingw32/scons puts the python scons libraries
107 in depkgs-mingw32/scons/lib64 but when running scons it looks for the
108 libs in depkgs-mingw32/scons/lib. So adding symlink from
109 depkgs-mingw32/scons/lib64 to depkgs-mingw32/scons/lib will fix the
112 You need the header files from the Microsoft VSS SDK. Unfortunately the SDK
113 can only be downloaded and installed on a Windows system. We do not have
114 the right to distribute it, so you must download it yourself.
115 You can find it on Microsoft's web-site at:
117 http://www.microsoft.com/downloads/details.aspx?FamilyID=0b4f56e4-0ccc-4626-826a-ed2c4c95c871&DisplayLang=en
119 If that link doesn't work then go to http://www.microsoft.com and search for
121 "download volume shadow copy service sdk"
123 we are currently using version 7.2 released 8/3/2005.
125 Normally the files will be installed in:
127 c:\Program Files\Microsoft\VSSSDK72
129 You only need to copy everything under the c:\Program Files\Microsoft\VSSSDK72\inc
130 directory into .../depkgs-mingw32/vss/inc. In doing so, please ensure that
131 the case in maintained on the directory and filenames -- some contain uppercase
134 The above only needs to be done once unless we change the cross-tools
135 or the dependencies versions. In general, you can run the script multiple
136 times with no problem. For it to work, you must have at a minimum the
149 and possibly other packages.
155 Finally, to build the Microsoft Windows version of Bacula, do the following:
157 cd .../bacula/src/win32
160 If all goes well, you will end with all the executables in the
161 .../bacula/src/win32/release directory, and the installer binary
162 containing everything will be named winbacula-xx.yy.zz.exe where
163 xx.yy.zz is the Bacula version you are building.
165 If you have an older build environment, you might do the following
166 to ensure that you pick up all the new Win32 changes:
175 Updating the 3rd party package patches
176 ======================================
178 If one of the patches changes in .../bacula/src/win32/patches, you will
179 need to update the corresponding dependency. You can install new patches
180 by doing the following (we assume the patch in question is for openssl).
182 cd .../bacula/src/win32
183 ./build-depkgs-mingw32 -C openssl
185 NOTE: The -C means clobber. Any local changes to the source code in
186 the .../depkgs-mingw32/src directory will be lost. The source
187 will be reextracted from the archive and the current patches
191 Adding a new global function or global data
192 ===========================================
197 The code from the following directories is built into bacula.dll:
200 .../bacula/src/libfind
201 .../bacula/src/win32/compat
203 A new function or data variable which must be accessed from outside
204 of bacula.dll requires special treatment. It must be specifically
207 New data variables are exported by adding the macro DLL_IMP_EXP to
208 the variable declaration in the header file. All exported variables
209 must be declared in a header file and MUST NOT be declared in a
210 source file referencing the variable. Example, src/lib/runscript.h:
212 extern DLL_IMP_EXP bool (*console_command)(JCR *jcr, const char *cmd);
216 extern int DLL_IMP_EXP num_jobs_run;
217 extern DLL_IMP_EXP dlist * last_jobs;
221 Exporting functions is now more or less automated. If you find that
222 a function name has been added, changed, or an argument modified,
223 simply do the following:
225 cd .../bacula/src/win32/lib
226 make (to build the .o files, note the link will fail)
227 ./make_def >bacula32.def # or >bacula64.def
229 This should rebuild the bacula.def file, but it uses relative paths
230 and assumes you have the directory structure noted above. If you
231 are using something different, you can set the NM variable at the
232 top of the make_def file to use an absolute path to the correct
235 ===== manual changing of bacula32.def or bacula64.def no longer necessary =====
236 If you want to do it manually, please see below:
237 Exporting a function requires a bit more work. You must determine the
238 C++ mangled name of the new function.
240 strings .../bacula/src/win32/lib/<file>.o | grep <symbol>
242 Note, strings often will not show the desired symbol. In that case,
245 nm .../bacula/src/win32/lib/<file>.o
247 Replace <file> with the base part of the name of the source code file
248 which contains the new function. Replace <symbol> with the name of
249 the new function. Remove the leading underscore and place the result
252 .../bacula/src/win32/lib/bacula32.def
253 === end manual changing of bacula32.def or bacula64.def ==========
255 If you add a new file, you will need to specify its name in
257 .../bacula/src/win32/lib/Makefile
259 .../bacula/src/win32/libbac/Makefile
264 The code from the .../bacula/src/cats directory is built into database
265 provider specific libraries of the form cats_<db>.dll.
267 The database specific portion <db> is mysql for MySQL, pgsql for
268 PostgreSQL, sqlite for SQLite, and bdb for the built-in Bacula database.
270 During installation of the Director, one of the database libraries is
271 copied to the system and renamed bacula_cats.dll.
273 A new function or data variable which must be accessed from outside
274 of bacula_cats.dll requires special treatment. It must be specifically
277 New data variables are exported by placing their name in the file
278 .../bacula/src/win32/cats/bacula_cats.def.
280 As with the bacula.def file above, this is now more or less automated.
281 When the link dies, simply do the following:
283 cd .../bacula/src/win32
284 make (to build the .o files, note the link will fail)
286 ./make_def >bacula_cats.def
288 This should rebuild the bacula_cats.def file. Note, if you have
289 changed any data entry points, you will need to modify the make_def
290 script -- it should be rather obvious.
293 ===== manual changing of bacula_cats.def no longer necessary =====
294 Exporting a function requires a bit more work. You must determine the
295 C++ mangled name of the new function.
297 strings .../bacula/src/win32/cats/cats_*/<file>.o | grep <symbol>
299 Note, strings often will not show the desired symbol. In that case,
302 nm .../bacula/src/win32/lib/<file>.o
304 Replace <file> with the base part of the name of the source code file
305 which contains the new function. Replace <symbol> with the name of
306 the new function. Remove the leading underscore and place the result
307 in the .../bacula/src/win32/cats/bacula_cats.def file.
308 === end manual changing of bacula_cats.def ==========
311 Running gdb on the Win32 files
312 ==================================================
313 You can use the mingw32 gdb to debug Bacula on Win32 by downloading
314 it from Source Forge:
316 http://sourceforge.net/project/showfiles.php?group_id=2435&package_id=20507
318 Download one of their .exe versions, which is an installer that you
319 can run on Win32 to install gdb. This gdb is built with mingw32 so will
320 run independently of any cygwin installation. Note, not all the releases
321 come with an installer. I had to go back 3 or 4 versions to find it. Otherwise
322 you can download the source and build it. Thanks to Eric Bollengier for
326 Structure of the MinGW32 build environment
327 ==========================================
329 The basic strategy is each Makefile in the various subdirectories includes
330 Makefile.inc, defines variables and rules specific to what is being built,
331 then includes Makefile.rules which defines all the rules.
333 Makefile.inc defines the locations of all the dependencies and the compiler
334 and linker flags. It is automatically created from Makefile.inc.in. Any
335 changes must be made to Makefile.inc.in not Makefile.inc or they will be
336 overwritten the next time Makefile.inc.in is updated.
338 Makefile.rules defines a bunch of macros to simplify building. It also
339 includes all the basic rules for building objects, GUI and console
342 Makefile.template is a template for creating new Makefiles, if you are
343 creating a new directory, copy Makefile.template to Makefile in that
344 directory and edit to suit.