1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/build/docs/visualstudio.rst Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,100 @@
1.4 +.. _build_visualstudio:
1.5 +
1.6 +======================
1.7 +Visual Studio Projects
1.8 +======================
1.9 +
1.10 +The build system contains alpha support for generating Visual Studio
1.11 +project files to aid with development.
1.12 +
1.13 +To generate Visual Studio project files, you'll need to have a configured tree::
1.14 +
1.15 + mach configure
1.16 +
1.17 +(If you have built recently, your tree is already configured.)
1.18 +
1.19 +Then, simply generate the Visual Studio build backend::
1.20 +
1.21 + mach build-backend -b VisualStudio
1.22 +
1.23 +If all goes well, the path to the generated Solution (``.sln``) file should be
1.24 +printed. You should be able to open that solution with Visual Studio 2010 or
1.25 +newer.
1.26 +
1.27 +Currently, output is hard-coded to the Visual Studio 2010 format. If you open
1.28 +the solution in a newer Visual Studio release, you will be prompted to upgrade
1.29 +projects. Simply click through the wizard to do that.
1.30 +
1.31 +Structure of Solution
1.32 +=====================
1.33 +
1.34 +The Visual Studio solution consists of hundreds of projects spanning thousands
1.35 +of files. To help with organization, the solution is divided into the following
1.36 +trees/folders:
1.37 +
1.38 +Build Targets
1.39 + This folder contains common build targets. The *full* project is used to
1.40 + perform a full build. The *binaries* project is used to build just binaries.
1.41 + The *visual-studio* project can be built to regenerate the Visual Studio
1.42 + project files.
1.43 +
1.44 + Performing the *clean* action on any of these targets will clean the
1.45 + *entire* build output.
1.46 +
1.47 +Binaries
1.48 + This folder contains common binaries that can be executed from within
1.49 + Visual Studio. If you are building the Firefox desktop application,
1.50 + the *firefox* project will launch firefox.exe. You probably want one of
1.51 + these set to your startup project.
1.52 +
1.53 +Libraries
1.54 + This folder contains entries for each static library that is produced as
1.55 + part of the build. These roughly correspond to each directory in the tree
1.56 + containing C/C++. e.g. code from ``dom/base`` will be contained in the
1.57 + ``dom_base`` project.
1.58 +
1.59 + These projects don't do anything when built. If you build a project here,
1.60 + the *binaries* build target project is built.
1.61 +
1.62 +Updating Project Files
1.63 +======================
1.64 +
1.65 +As you pull and update the source tree, your Visual Studio files may fall out
1.66 +of sync with the build configuration. The tree should still build fine from
1.67 +within Visual Studio. But source files may be missing and IntelliSense may not
1.68 +have the proper build configuration.
1.69 +
1.70 +To account for this, you'll want to periodically regenerate the Visual Studio
1.71 +project files. You can do this within Visual Studio by building the
1.72 +``Build Targets :: visual-studio`` project or by running
1.73 +``mach build-backend -b VisualStudio`` from the command line.
1.74 +
1.75 +Currently, regeneration rewrites the original project files. **If you've made
1.76 +any customizations to the solution or projects, they will likely get
1.77 +overwritten.** We would like to improve this user experience in the
1.78 +future.
1.79 +
1.80 +Moving Project Files Around
1.81 +===========================
1.82 +
1.83 +The produced Visual Studio solution and project files should be portable.
1.84 +If you want to move them to a non-default directory, they should continue
1.85 +to work from wherever they are. If they don't, please file a bug.
1.86 +
1.87 +Invoking mach through Visual Studio
1.88 +===================================
1.89 +
1.90 +It's possible to build the tree via Visual Studio. There is some light magic
1.91 +involved here.
1.92 +
1.93 +Alongside the Visual Studio project files is a batch script named ``mach.bat``.
1.94 +This batch script sets the environment variables present in your *MozillaBuild*
1.95 +development environment at the time of Visual Studio project generation
1.96 +and invokes *mach* inside an msys shell with the arguments specified to the
1.97 +batch script. This script essentially allows you to invoke mach commands
1.98 +inside the MozillaBuild environment without having to load MozillaBuild.
1.99 +
1.100 +While projects currently only utilize the ``mach build`` command, the batch
1.101 +script does not limit it's use: any mach command can be invoked. Developers
1.102 +may abuse this fact to add custom projects and commands that invoke other
1.103 +mach commands.
