top bar

Building MM on Windows

Revision as of 13:24, 9 October 2013 by Mark Tsuchida (Talk | contribs)

Preparation

First make sure you have enough hard disk space. 5 GB is probably enough.

Directory structure for the source code

Create a directory named projects. The projects directory may reside anywhere you like and will contain the subdirectories micro-manager1.4, 3rdpartypublic, and 3rdparty.

Downloading the source code

To check out the Micro-Manager Source Code, first obtain a Subversion client. From projects/, run:

svn co https://valelab.ucsf.edu/svn/micromanager2/trunk/ micro-manager1.4
svn co https://valelab.ucsf.edu/svn/3rdpartypublic/

Required tools and applications

To build the entire application from the source code, you will need to install the following tools:

To build device adapters:

  1. Microsoft Visual Studio 2008 (Express is fine, and doesn't cost anything.)

(Work is underway to migrate Micro-Manager to Visual Studio 2010.)

Additionally, to build the entire Micro-Manager package:

  1. JDK Standard Edition 6 or later
  2. Apache Ant 1.8.1 or later (tested with 1.9.2)

Tell the build tools where to find Java and Ant by opening the System control panel / Advanced system settings / Environment Variables / System variables and addding the following new entries:

ANT_HOME=C:\apache-ant-1.9.2 (or path to Ant)
JAVA_HOME=C:\Program Files\Java\jdk1.6.0_20 (or path to Java)
PATH=%PATH%;%ANT_HOME%\bin

Device libraries and SDKs

Some device adapter require the installation of manufacturer's SDKs in order to build. All SDKs should be installed in the <root>/projects/3rdparty directory. The actual names of SDK directories should match the paths in the corresponding header files in the Micro-manager source code for device adapters.

If you don't want to build one or more device adapters (because you don't have the SDK), you should remove corresponding projects from the master solution: MMCoreJ_wrap.sln.

To add a device adapter to the automated build, use Visual Studio 2008 to add the device adapter project (a .vcproj file) to the MMCoreJ_wrap.sln or MMCoreJ_wrap_x64.sln. Under the device adapter's project properties, make sure the device adapter has this command under Build Events > Post-build Event:

copy "$(TargetPath)" ..\..\bin_$(PlatformName)

and a Linker > General > Output File of

$(OutDir)/mmgr_dal_YourDeviceName.dll

Setting up library paths

The project files in the repository should have the correct path settings.

To deal with the flood of text in the Output window, in the Solution Explorer right-click and build one project at a time.

If in Visual Studio you get an error:

       Target(FOO) does not match the Linker's OutputFile property value (BAR) ...

You could right-click on the project > properties > Configuration Properties > General > Target Name and add the leading "mmgr_dal_" to the beginning of $(ProjectName) to satisfy it.

Setting up 64-bit support on Visual C++ Express

Visual Studio Express does not include 64-bit compiler support out of the box. To compile x64 libraries in addition to Win32, you need to install the Windows SDK: http://msdn.microsoft.com/en-us/windows/bb980924

After installation you should find the x64 specific libraries at a path similar to:

       C:\Program Files\Microsoft SDKs\Windows\v7.1\Lib\x64

To build your x64 project you would need to make sure this is in the 'Additional Library Directories' setting in your project, specifically in Project > Properties > Configuration Properties > Linker > Additional Library Directories. If you do not do this you will get linker errors similar to:

       LINK: fatal error LNK1181: cannot open input file FOO.lib

Building the C++ layer: MMCore and device adapters

You can build C++ part of the project by opening MMCoreJ_wrap.sln in Visual Studio 2008 and running the full build. This will build the MMCore, Java wrappers and all device adapters. You can remove any device adapter project from the solution if you don't have the corresponding SDK or if you don't need to build it.

The C++ components can also be built using the batch file buildscripts/buildCpp.bat.

Building the Java layer: Micro-Manager Studio

The Java layer of the Micro-Manager can be build using the Apache Ant utility with the build.xml project file, located in the directories for each Java component (mmstudio, acqEngine, plugins, autofocus).

Building these components currently requires that MMCoreJ.jar be manually placed in <root>/projects/micro-manager-1.4/build/Java.

In the mmstudio directory from the command line, run:

 ant jar

Which should produce MMJ_.jar in <root>/projects/micro-manager-1.4/build/Java.

The same command should work in acqEngine, plugins, the individual plugin subdirectories, and autofocus (acqEngine depends on mmstudio, and plugins depend on mmstudio and acqEngine, so they must be built in that order).

Building the full source in one step

You can build the C++, Java, and Clojure components in one step by typing, in <root>/projects/micro-manager-1.4, the following command:

 ant stage -Dmm.architecture=Win32 -Dmm.configuration=Release -Dmm.build.failonerror=false

The value for mm.architecture can also be x64. The mm.build.failonerror=false setting causes device adapters and plugins to be skipped if they do not compile. Built files are placed in the stage/Release/Win32 directory.

Using Visual Studio 2010 (or 2012)

Work is underway (by Mark) to migrate Micro-Manager to Visual Studio 2010 (in which the project file format has changed significantly from VS2008).

To setup a 32/64-bit build environment with VS2010,

Note
The order if installation is important. In particular, the SDK 7.1 installer will fail if VS2010 SP1 is installed first. If you are in that situation, the only way out that I have found is to go to Control Panel > "Uninstall a program", uninstall everything with "Microsoft Visual ... 2010" in its name (Redistributable, Runtime, Express, Compilers, Service Pack, Tools for Office Runtime), and start over.
Note
It is also possible that installation of the Windows SDK can fail (even if you don't have VS2010 installed) if you have a newer version of "Microsoft Visual C++ 2010 Redistributable" (which is installed by various programs, including some versions of Micro-Manager) than the version that the SDK installer tries to install (which is 10.0.30319).

Even before the whole project migrates to VS2010, building individual device adapters using VS2010 is (usually) relatively easy. Open the .vcproj file for a device adapter in VS2010, and follow the instructions to auto-convert (a .vcxproj file is generated). Then, in Project Properties,

  • Reset Linker Output File to "inherit from parent or project defaults", which gives you $(OutDir)$(TargetName)$(TargetExt), and set Target Name to mmgr_dal_$(ProjectName)
  • Set Platform Toolset to WindowsSDK7.1

Make sure to do both after selecting All Platforms and All Configurations.

I have not tried VS2012 yet, but the necessary steps are likely to be similar to VS2010. According Microsoft, it looks like VS2010 SP1 project files will work unmodified in VS2012 if both versions are installed on the computer.




Note
What follows is a new version of this page corresponding to the upgrade to Visual Studio 2010 SP1 planned on Oct 10, 2013. --Mark Tsuchida (talk) 14:24, 9 October 2013 (PDT)


Before you start

First make sure you have enough hard disk space. 15 GB is probably enough.


Setting up the required tools

Subversion client

You will need a Subversion client. GUI clients such as TortoiseSVN also work well.

Microsoft Visual Studio 2010 SP1 Express

Micro-Manager's C++ components (Core, MMCoreJ, MMCorePy, and device adapters) are currently built using Visual Studio 2010 Express. To install a complete build environment, follow these instructions (all are free downloads):

  1. Open Control Panel > "Uninstall a program". If there are any items named Microsoft Visual C++ 2010 Redistributable with version number greater than 10.0.30319, uninstall them (see the note below for why).
  2. Install Microsoft Windows SDK 7.1 (http://www.microsoft.com/en-us/download/details.aspx?id=8279). If the installer complains that .NET Framework 4 is required, cancel the SDK install and first install the .NET Framework (from http://www.microsoft.com/en-us/download/details.aspx?id=17851). If installation of the SDK fails, see the notes below.
  3. Install Visual C++ 2010 Express from http://www.microsoft.com/visualstudio/eng/downloads#d-2010-express.
  4. Upgrade to Visual Studio 2010 SP1 (http://www.microsoft.com/en-us/download/details.aspx?id=23691).
  5. Repair the compilers that come with Windows SDK 7.1 by installing this package: http://www.microsoft.com/en-us/download/details.aspx?id=4422
Note
The order if installation is important. In particular, the SDK 7.1 installer will fail if VS2010 SP1 is installed first. If you are in that situation, the only way out that I have found is to go to Control Panel > "Uninstall a program", uninstall everything with "Microsoft Visual ... 2010" in its name (Redistributable, Runtime, Express, Compilers, Service Pack, Tools for Office Runtime), and start over.
Note
It is also possible that installation of the Windows SDK can fail (even if you don't have VS2010 installed) if you have a newer version of Microsoft Visual C++ 2010 Redistributable than the version that the SDK installer tries to install (which is 10.0.30319). The VC++ Redistributable is installed by various programs, including some versions of Micro-Manager)

Java Development Kit (JDK) for Java Standard Edition (Java SE)

Download and install from Oracle. Version 6 or later is required. The official Micro-Manager build currently uses JDK 6.

You do not need the JDK if you are only building device adapters or other C++ components.

Apache Ant

Apache Ant is the build tool used to automate the full Windows build of Micro-Manager. Version 1.8.1 or later is required (tested with 1.9.2).

Download the binary package.

You do not need Ant if you are only building device adapters of other C++ components.

Environment variables

For building the Java and Clojure components using Ant, the following environment variables need to be set correctly. They can be added in Control Panel > System and Security > System > "Advanced system settings" > "Environment variables...".

  • JAVA_HOME: set to the path to your JDK installation, e.g. C:\Program Files\Java\jdk1.6.0_45. Do not add quotes to the value, even if it contains spaces.
  • ANT_HOME: set to the path to your Ant installation (whereever you placed the extracted binary package), e.g. C:\apache-ant-1.9.1. Do not add quotes to the value, even if it contains spaces.
  • PATH: It is convenient to add Ant to the command search path. You can append ;%ANT_HOME%\bin to the end of the System PATH varialbe, or add a User variable named PATH and set its value to %PATH%;%ANT_HOME%\bin.


Preparing the source code

Directory layout

Create a directory named projects (the name is not important, but we will refer to this name below). The projects directory may reside anywhere you like and will contain the subdirectories micromanager, 3rdpartypublic, and (optionally) 3rdparty.

All directories mentioned below that don't start with project are relative to projects\micromanager.

Obtaining the source code

Checkout the Micro-Manager Source Code inside the projects directory, using your Subversion client. This should result in the following directories:

projects\micromanager
projects\3rdpartypublic

Vendor SDKs and libraries

If you have third-party libraries (e.g. from device vendors), create the directory projects\3rdparty and place them in an appropriately named subdirectory.

If you are building a device adapter included in the Micro-Manager Subversion repository, and it requires third-party libraries, you will need to place them in the correct directory within projects\3rdparty, as determined by the settings in the Visual Studio project file for the adapter. Alternatively, you can locally edit the build settings in the project file.

(There are cases where the location of a header file is hard-coded (relative to the 3rdparty directory) in the source (.h and .cpp) files. This practice is discouraged, but if you encounter it, you might have to edit the path.)


Building Micro-Manager

Building single device adapters

Open the project file (.vcxproj) for the device adapter in Visual Studio. Select the Debug or Release configuration and the Win32 or x64 platform from the drop-down menus (for various reasons, the Debug configuration does not work for all device adapters). If everything is configured correctly as described above, you should be able to simply select Build.

Visual Studio will ask you if you want to save a "solution" (.sln file). This is up to you. In Visual Studio 2010 and later, the solution is little more than a list of project files to be built together, so our policy is not to include solution files for each project in the repository (but see below about the master micromanager.sln file).

The build binaries are placed under the directory build, within the device adapter directory.

Some device adapters (those made up of more than one project) may not build correctly by this method. In that case, build it from micromanager.sln as described below.

Building multiple device adapters, MMCoreJ, or all C++ components

Open micromanager.sln (in the root of projects\micromanager). Visual Studio will warn you that some projects are missing (they are the closed-source device adapters), but you can ignore that message. Then (after setting the configuration and platform) simply right-click the desired projects and select Build.

Note that the built binaries are placed under the directory build at the root of projects\micromanager.

If you build MMCoreJ, MMCoreJ_wrap.dll will be generated. Additionally, Java source files are generated in build\intermediates\Swig\MMCoreJ\. These files are compiled into MMCoreJ.jar in a separate step by Ant (see below).

You can also build all available projects by right-clicking the Solution and choosing Build.

Building MMCorePy

First, you need to install Python 2.7 and Numpy 1.7 (different versions, such as Python 2.6, may work if the project settings are appropriately edited).

To tell Visual Studio where to find the Python installation, open MMCorePy_wrap\Python.props in a text editor (these settings can be edited in Visual Studio, but it's simpler to explain how to manually edit this file). Find the block that starts with PropertyGroup Label="UserMacros", which contains a line for PythonDir. Set its value to the path to your Python installation. If you installed Python 2.7 in the default location, you probably just need to remove the -$(Platform) part.

Once this is done, you should be able to build MMCorePy from micromanager.sln by the steps described above. Make sure to select the Release configuration and the platform that matches your Python binaries.

The build will generate _MMCorePy.pyd (the extension module) and MMCorePy.py (the Python wrapper module).

Building individual Java components

On Windows, Micro-Manager's Java components are built using Apache Ant.

Each Java (and Clojure) component has a build.xml (an Ant build script):

 MMCoreJ_wrap\build.xml
 mmstudio\build.xml
 acqEngine\build.xml
 plugins\*\build.xml
 autofocus\build.xml

To build one of these components, open the Command Prompt, and change to the directory containing the build script. Then simply type

 ant jar

This should produce the jar file in build\Java. (Ant automatically uses the build.xml file in the current directory.)

For example,

 cd MMCoreJ_wrap
 ant jar

will produce build\Java\MMCoreJ.jar.

Some of the Java components depend on each other. When building the components one by one, you will need to build them in the order listed above (see below for building everything automatically).

To build MMCoreJ.jar (and, by transitive dependency, any of the other Java components), you need to have built the C++ part of MMCoreJ (either in Visual Studio as described above, or using Ant as described below) before running Ant.

Building Clojure components (acqEngine and some of the plugins) requires a loadable MMCoreJ_wrap.dll. "Loadable", in this context, means that it is built for the same architecture (32-bit vs 64-bit) as your Java runtime (on which Ant is running). If you are using a 32-bit JDK but have built MMCoreJ for 64-bit, you will also need to build the 32-bit MMCoreJ_wrap.dll (and vice versa). The MMCoreJ_wrap.dll for the two architectures go in different directories, so there is no harm in building both in the same source tree.

Building all components

Open the Command Prompt, and change to the projects\micromanager directory. Type

 ant -p

This should list a number of options. To build all C++ components (similar to building the micromanager.sln Solution in Visual Studio), type

 ant build-cpp -Dmm.build.failonerror=false -Dmm.architecture=Win32

Setting the mm.build.failonerror property to false allows the build to continue even if some of the projects (e.g. device adapters that depend on libraries you don't have) fail to build. (But you will want to check that the ones you want did build. Look in the build directory.)

The architecture (what Visual Studio calls 'platform' - but we reserve that term for Windows vs OS X vs Linux) can be set to Win32 or x64.

The command

 ant build -Dmm.build.failonerror=false -Dmm.architecture=Win32

will build everything (all C++, Java, and Clojure compoenets).

There is also a build-java target that you can use to build just the Java and Clojure components (it will not try to build the C++ components).

The stage and package targets are not yet fully implemented for general use.


© Micro-Manager : Vale Lab, UCSF 2006-2011 | All Rights Reserved | Contact