build/docs/visualstudio.rst

   1 .. _build_visualstudio:
   2
   3 ======================
   4 Visual Studio Projects
   5 ======================
   6
   7 The build system automatically generates Visual Studio project files to aid
   8 with development, as part of a normal ``mach build`` from the command line.
   9
  10 You can find the solution file at ``$OBJDIR/msvc/mozilla.sln``.
  11
  12 If you want to generate the project files before/without doing a full build,
  13 running ``./mach configure && ./mach build-backend -b VisualStudio`` will do
  14 so.
  15
  16
  17 Structure of Solution
  18 =====================
  19
  20 The Visual Studio solution consists of hundreds of projects spanning thousands
  21 of files. To help with organization, the solution is divided into the following
  22 trees/folders:
  23
  24 Build Targets
  25    This folder contains common build targets. The *full* project is used to
  26    perform a full build. The *binaries* project is used to build just binaries.
  27    The *visual-studio* project can be built to regenerate the Visual Studio
  28    project files.
  29
  30    Performing the *clean* action on any of these targets will clean the
  31    *entire* build output.
  32
  33 Binaries
  34    This folder contains common binaries that can be executed from within
  35    Visual Studio. If you are building the Firefox desktop application,
  36    the *firefox* project will launch firefox.exe. You probably want one of
  37    these set to your startup project.
  38
  39 Libraries
  40    This folder contains entries for each static library that is produced as
  41    part of the build. These roughly correspond to each directory in the tree
  42    containing C/C++. e.g. code from ``dom/base`` will be contained in the
  43    ``dom_base`` project.
  44
  45    These projects don't do anything when built. If you build a project here,
  46    the *binaries* build target project is built.
  47
  48 Updating Project Files
  49 ======================
  50
  51 Either re-running ``./mach build`` or ``./mach build-backend -b VisualStudio``
  52 will update the Visual Studio files after the tree changes.
  53
  54 Moving Project Files Around
  55 ===========================
  56
  57 The produced Visual Studio solution and project files should be portable.
  58 If you want to move them to a non-default directory, they should continue
  59 to work from wherever they are. If they don't, please file a bug.
  60
  61 Invoking mach through Visual Studio
  62 ===================================
  63
  64 It's possible to run mach commands via Visual Studio. There is some light magic
  65 involved here.
  66
  67 Alongside the Visual Studio project files is a batch script named ``mach.bat``.
  68 This batch script sets the environment variables present in your *MozillaBuild*
  69 development environment at the time of Visual Studio project generation
  70 and invokes *mach* inside an msys shell with the arguments specified to the
  71 batch script. This script essentially allows you to invoke mach commands
  72 inside the MozillaBuild environment without having to load MozillaBuild.
  73
  74 Projects currently utilize the ``mach build`` and ``mach clobber`` commands
  75 for building and cleaning the tree respectively. Note that running ``clobber``
  76 deletes the Visual Studio project files, and running ``build`` recreates them.
  77 This might cause issues while Visual Studio is running. Thus a full rebuild is
  78 currently neither recommended, nor supported, but incremental builds should work.
  79
  80 The batch script does not limit its use: any mach command can be invoked.
  81 Developers may use this fact to add custom projects and commands that invoke
  82 other mach commands.