Building MapGuide on windows: Made easier (updated)

One of the first things I did once I acquired svn commit rights was to check in a set of batch files that should make building MapGuide from windows much easier than it was previously.

If you update your working copy, you will find some new batch files:

MgDev\build.bat
Tools\Maestro\build.bat
Installer\build.bat

These batch files were modeled after the FDO batch files, so if you have experienced building FDO from source, this should be a similar experience.

Before you run these batch files, make sure you have the following requirements.

1. You have copied the FDO binaries into the MgDev\Oem\FDO\bin\%CONFIG% folder (where %CONFIG% is Debug or Release)
2. You have copied the FDO headers into the MgDev\Oem\FDO\Inc folder
3. You have copied the FDO library files (*.lib) into the MgDev\Oem\FDO\Lib folder

Make sure you are using the latest FDO binaries built from trunk or you are using the latest binary SDK (currently 3.4.0-RC1)

Also make sure you have the following software installed:

1. Java SDK (to build the MapGuide Java API)
2. Apache Ant (to build Fusion)
3. Wix 3.0 (to build the installer)
4. Paraffin (to regenerate some Wix project files)
5. Doxygen (to build the documentation)

Once you have all these requirements satsified, you'll need to tweak some settings in the batch files.

Edit MgDev\build.bat and change JAVA_HOME, ANT_HOME and DOXYGEN to match the paths of your Java SDK, Apache Ant and doxygen installations.

Edit Installer\build.bat and change PARAFFIN to match the path to your paraffin.exe

Now we can begin the build which will go in this order.

1. Build Oem components
2. Build Server
3. Build Web
4. Build Documentation
5. Copy Server to staging area
6. Copy Web to staging area
7. Copy Documentation to staging area
8. Build Maestro
9. Prepare staging area for wix
10. Regenerate wix files from staging area
11. Build Installer

MgDev\build.bat will take care of steps 1 to 7
Tools\Maestro\build.bat will take care of step 8
Installer\build.bat will take care of steps 9 to 11

Building the Oem, Server, Web and Docs

MgDev\build.bat exposes the following parameters:

-c=BuildType
-w=Component
-a=Action
-o=OutputDir

BuildType can be Release (default) or Debug
Component can be all (default), oem, server, web or doc
Action can be build(default), install, clean
OutputDir is the directory where the files will be copied. Only applies if Action is install.

The Action parameter can be fine-grained by component:

eg. -a=clean -w=oem will only clean the oem component.
eg. -a=build -w=server will only build the server

Running MgDev\build.bat without any parameters is the same as having:
-a=build -w=all

Which will build oem, server, web and docs (in that order)

Preparing the staging area

The staging area serves two purposes.

1. As a "clean" installation. You can use it to verify that all the required files are there for the server to run.
2. As a foundation for the wix installer.

To copy the files to a staging area run:

build.bat -a=install -w=all -o=C:\MyStagingArea

When copying files, all the server-related files go in the Server subdirectory. All the web-related files go in the WebServerExtensions subdirectory

Building Maestro

Building Maestro is straightforward, you don't really have to use the batch file as running msbuild on the Maestro solution file will suffice. The only important thing is to remember is where the Maestro binaries are, because we need to reference this location when building the wix installer.

Preparing the staging area

Before we build the wix installer, we need to prepare the staging area with additional files, such as the Apache Web Server, Tomcat and Php.

Installer\build.bat exposes the following parameters:

-c=BuildType
-a=Action
-srv=ServerDirectory
-web=WebExtensionsDirectory
-maestro=MaestroDirectory

BuildType can be Release (default) or Debug
Action can be build (default), clean, regen or prepare
ServerDirectory is the directory where the server has been deployed to (from the previous batch file)
WebExtensionsDirectory is the directory where the web extensions has been deployed to. We will be referring to this directory when preparing our staging area.
MaestroDirectory is the directory where the Maestro binaries are located

The -srv, -web and -maestro parameters are optional. If omitted the following default values are used.

-srv=..\MgDev\%CONFIG%\Server (where %CONFIG% is Debug or Release)
-web=..\MgDev\%CONFIG%\WebServerExtensions (where %CONFIG% is Debug or Release)
-maestro=..\Tools\Maestro\Maestro

To prepare the staging area, we run:

build.bat -a=prepare -web=C:\MyStagingArea\WebServerExtensions

Regenerating the wix project files

We use a tool called Paraffin to regenerate the file listings. The benefit of having a staging area, as opposed to directly using the default project output directory is that we don't get those useless .svn directories that can potentially add lots of unneeded cruft to our installer.

To regenerate the wix project files we run:

build.bat -a=regen -srv=C:\MyStagingArea\Server -web=C:\MyStagingArea\WebServerExtensions -maestro=C:\MyMaestroStagingArea

Again, the batch file has default paths specified if you don't include these parameters. Just make sure that your files are actually in the default directories!

Building the installer

Once all that is done, there is the final step of building the actual windows installer. Simply run build.bat without parameters, and after a few minutes you'll have a brand shiny msi installer sitting in Installer\Installers\MapGuide\bin\release ready to go.

In summary

From source code to msi installer.

1. MgDev\build.bat -a=build -w=all
2. MgDev\build.bat -a=install -w=all -o=C:\Staging\
3. Tools\Maestro\Maestro\Update %CONFIG% Environment.bat
4. Tools\Maestro\build.bat -a=buildinstall -o=C:\Staging\Maestro
5. Installer\build.bat -a=prepare -web=C:\Staging\WebServerExtensions
6. Installer\build.bat -a=regen -srv=C:\Staging\Server -web=C:\Staging\WebServerExtensions -maestro=C:\Staging\Maestro
7. Installer\build.bat -a=build -srv=C:\Staging\Server -web=C:\Staging\WebServerExtensions -maestro=C:\Staging\Maestro

I hope these batch files will greatly improve your build experience in windows. If you do encounter issues, please file tickets on the MapGuide Trac

Edit: Fixed step 5. in the bite-sized build summary
Edit#2: More missing steps added