michael@0: .. _build_visualstudio:
michael@0: 
michael@0: ======================
michael@0: Visual Studio Projects
michael@0: ======================
michael@0: 
michael@0: The build system contains alpha support for generating Visual Studio
michael@0: project files to aid with development.
michael@0: 
michael@0: To generate Visual Studio project files, you'll need to have a configured tree::
michael@0: 
michael@0:    mach configure
michael@0: 
michael@0: (If you have built recently, your tree is already configured.)
michael@0: 
michael@0: Then, simply generate the Visual Studio build backend::
michael@0: 
michael@0:    mach build-backend -b VisualStudio
michael@0: 
michael@0: If all goes well, the path to the generated Solution (``.sln``) file should be
michael@0: printed. You should be able to open that solution with Visual Studio 2010 or
michael@0: newer.
michael@0: 
michael@0: Currently, output is hard-coded to the Visual Studio 2010 format. If you open
michael@0: the solution in a newer Visual Studio release, you will be prompted to upgrade
michael@0: projects. Simply click through the wizard to do that.
michael@0: 
michael@0: Structure of Solution
michael@0: =====================
michael@0: 
michael@0: The Visual Studio solution consists of hundreds of projects spanning thousands
michael@0: of files. To help with organization, the solution is divided into the following
michael@0: trees/folders:
michael@0: 
michael@0: Build Targets
michael@0:    This folder contains common build targets. The *full* project is used to
michael@0:    perform a full build. The *binaries* project is used to build just binaries.
michael@0:    The *visual-studio* project can be built to regenerate the Visual Studio
michael@0:    project files.
michael@0: 
michael@0:    Performing the *clean* action on any of these targets will clean the
michael@0:    *entire* build output.
michael@0: 
michael@0: Binaries
michael@0:    This folder contains common binaries that can be executed from within
michael@0:    Visual Studio. If you are building the Firefox desktop application,
michael@0:    the *firefox* project will launch firefox.exe. You probably want one of
michael@0:    these set to your startup project.
michael@0: 
michael@0: Libraries
michael@0:    This folder contains entries for each static library that is produced as
michael@0:    part of the build. These roughly correspond to each directory in the tree
michael@0:    containing C/C++. e.g. code from ``dom/base`` will be contained in the
michael@0:    ``dom_base`` project.
michael@0: 
michael@0:    These projects don't do anything when built. If you build a project here,
michael@0:    the *binaries* build target project is built.
michael@0: 
michael@0: Updating Project Files
michael@0: ======================
michael@0: 
michael@0: As you pull and update the source tree, your Visual Studio files may fall out
michael@0: of sync with the build configuration. The tree should still build fine from
michael@0: within Visual Studio. But source files may be missing and IntelliSense may not
michael@0: have the proper build configuration.
michael@0: 
michael@0: To account for this, you'll want to periodically regenerate the Visual Studio
michael@0: project files. You can do this within Visual Studio by building the
michael@0: ``Build Targets :: visual-studio`` project or by running
michael@0: ``mach build-backend -b VisualStudio`` from the command line.
michael@0: 
michael@0: Currently, regeneration rewrites the original project files. **If you've made
michael@0: any customizations to the solution or projects, they will likely get
michael@0: overwritten.** We would like to improve this user experience in the
michael@0: future.
michael@0: 
michael@0: Moving Project Files Around
michael@0: ===========================
michael@0: 
michael@0: The produced Visual Studio solution and project files should be portable.
michael@0: If you want to move them to a non-default directory, they should continue
michael@0: to work from wherever they are. If they don't, please file a bug.
michael@0: 
michael@0: Invoking mach through Visual Studio
michael@0: ===================================
michael@0: 
michael@0: It's possible to build the tree via Visual Studio. There is some light magic
michael@0: involved here.
michael@0: 
michael@0: Alongside the Visual Studio project files is a batch script named ``mach.bat``.
michael@0: This batch script sets the environment variables present in your *MozillaBuild*
michael@0: development environment at the time of Visual Studio project generation
michael@0: and invokes *mach* inside an msys shell with the arguments specified to the
michael@0: batch script. This script essentially allows you to invoke mach commands
michael@0: inside the MozillaBuild environment without having to load MozillaBuild.
michael@0: 
michael@0: While projects currently only utilize the ``mach build`` command, the batch
michael@0: script does not limit it's use: any mach command can be invoked. Developers
michael@0: may abuse this fact to add custom projects and commands that invoke other
michael@0: mach commands.