man/xbuild.1

   1 .TH "xbuild" 1
   2 .SH NAME
   3 xbuild \- Mono's tool to build MSBuild project files
   4 .SH SYNOPSIS
   5 .B xbuild
   6 [option] [project-file]
   7 .SH DESCRIPTION
   8 xbuild can be used to build MSBuild project files. Integrated Development
   9 Environments like MonoDevelop and "Microsoft Visual Studio .NET" use msbuild
  10 project file format.
  11
  12 xbuild takes the path of the project or solution file to build, as the main argument.
  13 If no file is specified then it tries to build any solution file or project file in
  14 the current directory, that has a *proj extension.
  15 .SH OPTIONS
  16 .TP
  17 .B \//target:T1[,TN]
  18 List of targets to build
  19 .TP
  20 .B \//property:Name=Value
  21 Set or override project properties
  22 .TP
  23 .B \//logger:<logger>
  24 Custom logger to log build events
  25 .TP
  26 .B \//toolsversion:version , /tv:version
  27 Specify the toolset version to use.
  28
  29 Eg. /tv:4.0
  30     This would cause 4.0 version of the Microsoft.Common.targets (among others) to be used. This overrides
  31     the value specified in a project file.
  32
  33 Valid values: 2.0, 3.0, 3.5 and 4.0
  34 .TP
  35 .B \//verbosity:<level>
  36 Logger verbosity level : quiet, minimal, normal, detailed, diagnostic
  37 .TP
  38 .B \//validate
  39 Validate the project file against the schema
  40 .TP
  41 .B \//validate:<schema>
  42 Validate the project file against the specified schema
  43 .TP
  44 .B \//consoleloggerparameters:<params> , /clp:<params>
  45 Parameters for the console logger : PerfomanceSummary, Summary, NoSummary, NoItemAndPropertyList, Verbosity
  46 .TP
  47 .B \//filelogger[n] , /fl[n]
  48 Logs the output to a file, named 'msbuild.log' by default. If the optional number 'n' is
  49 specified, then it logs to 'msbuild[n].log' . Parameters for this logger, including
  50 the log file name can be specified via a corresponding /flp[n] option. Default verbosity
  51 for file loggers is 'detailed. 'n' can be between 1-9.
  52 .TP
  53 .B \//fileloggerparameters[n]:<params> , /flp[n]:<params>
  54 Parameters for a file logger. This implies a corresponding /fl[n]. 'n' can be between
  55 1-9, and is used to add upto 10 file loggers. Parameters can be, besides the ones available
  56 for console logger:
  57 .RS
  58 .TP
  59 .I LogFile=<file>
  60 File to which the build log will be written.
  61 .TP
  62 .I Append
  63 If this is used, then the log file is appended to, else a new one will be created.
  64 .TP
  65 .I Encoding=<encoding>
  66 Encoding to use for the log file, eg. UTF-8, ASCII.
  67 .TP
  68 Eg: xbuild foo.csproj /flp:Verbosity=normal "/flp1:LogFile=build.log;Append;Encoding=ASCII"
  69 .RE
  70 .TP
  71 .B \//nologo
  72 Don't show the initial xbuild banner
  73 .TP
  74 .B \//help
  75 Show xbuild usage
  76 .TP
  77 .B \//version
  78 Display xbuild version
  79 .SH ENVIRONMENT VARIABLES
  80 .TP
  81 .I "XBUILD_EMIT_SOLUTION"
  82 If this variable is set, then the project file generated from a solution
  83 file is emitted.
  84 .TP
  85 .I "XBUILD_LOG_REFERENCE_RESOLVER"
  86 References are resolved by trying a list of assembly search paths ($(AssemblySearchPaths)).
  87 If xbuild is unable to resolve a reference, then it logs details of why the various
  88 search paths failed. If this variable is set, then it logs the same even for references
  89 that were resolved successfully. These logs show up if the verbosity is set to detailed
  90 or higher.
  91 .TP
  92 .I "MSBuildExtensionsPath"
  93 MSBuild extensions are usually installed in $(MSBuildExtensionsPath), which xbuild resolves
  94 to $prefix/lib/mono/xbuild . When used in Import, like:
  95
  96   <Import Project="$(MSBuildExtensionsPath)\\TestTargets.targets"/>
  97
  98 xbuild tries various values for the msbuild property $(MSBuildExtensionsPath), in order:
  99
 100   1. Paths specified in the environment variable $MSBuildExtensionsPath.
 101   2. /Library/Frameworks/Mono.framework/External/xbuild on Mac OSX.
 102   3. $XDG_CONFIG_HOME/xbuild/tasks (or Environment.SpecialFolder.ApplicationData)
 103   4. $prefix/lib/mono/xbuild (default location)
 104
 105 Anywhere else in the project files, $(MSBuildExtensionsPath) will always resolve to the default
 106 location. This is a xbuild-only feature.
 107 This is also applicable for the properties $(MSBuildExtensionsPath32) and $(MSBuildExtensionsPath64),
 108 and the environment variables have the corresponding names - MSBuildExtensionsPath32/64 .
 109 .TP
 110 .I "XBUILD_FRAMEWORK_FOLDERS_PATH"
 111 With ToolsVersion 4.0, projects can target arbitrary frameworks referenced by TargetFrameworkMoniker,
 112 which is of the format:
 113
 114   Identifier,Version=<version>[,Profile=<profile>]
 115
 116 Eg. ".NETFramework,Version=v4.0"
 117
 118 The 3 parts of the moniker are given by the msbuild properties:
 119
 120   $(TargetFrameworkIdentifier), $(TargetFrameworkVersion) and $(TargetFrameworkProfile)
 121
 122 This moniker maps to a framework description file on disk:
 123
 124   <framework_root>/Identifier/Version/[Profile]/RedistList/FrameworkList.xml
 125
 126 This file is used to determine the path where to find the framework assemblies for this particular framework.
 127
 128 Framework root here is configurable and is resolved in the following order:
 129
 130 .nf
 131   1. Paths specified in the environment variable $XBUILD_FRAMEWORK_FOLDERS_PATH
 132   2. /Library/Frameworks/Mono.framework/External/xbuild-frameworks on Mac OSX.
 133   3. MSBuild property $(TargetFrameworkRoot)
 134   4. $prefix/lib/mono/xbuild-frameworks (default location)
 135 .fi
 136
 137 XBuild tries the paths given above, in order, till it finds a FrameworkList.xml for the moniker.
 138 Running with /v:detailed or higher verbosity will show the various paths that it tries.
 139
 140 The FrameworkList.xml itself just has a root element like:
 141
 142   <FileList  Name=".NET Framework 3.5" TargetFrameworkDirectory="..\\..\\..\\..\\3.5" IncludeFramework="v3.0">
 143   </FileList>
 144
 145 Here the TargetFrameworkDirectory attribute specifies the directory where the assemblies for
 146 this particular framework can be found. If this is not set, then the parent of the folder
 147 containing the xml file is taken as the framework directory.
 148
 149 IncludeFramework attribute specifies the version of a framework (under the *same* $(TargetFrameworkIdentifier))
 150 which should be included in the final list of Target framework directories.
 151
 152 .TP
 153 .I "XBUILD_COLORS"
 154 If this variable is set, it contains a string of the form
 155 "type=foreground,type=.." that specifies which color to use to display
 156 errors/warnings etc on some terminals. Type here can be:
 157
 158 .nf
 159         errors, warnings, messages or events
 160
 161         events: These are project/target/task start and end event
 162                 messages.
 163 .fi
 164
 165 .Sp
 166 The possible colors for foreground are:
 167 .B black, red, brightred, green, brightgreen, yellow, brightyellow,
 168 blue, brightblue, magenta, brightmagenta, cyan, brightcyan, grey,
 169 white and brightwhite.
 170
 171 .Sp
 172 For example, you could set this variable from your shell:
 173 .nf
 174         export XBUILD_COLORS
 175         XBUILD_COLORS=errors=brightred,warnings=blue
 176 .fi
 177 .Sp
 178
 179 You can disable the built-in color scheme by setting this variable to
 180 "disable".
 181
 182 .SH NOTES
 183 On Mac OSX, for locating pkg-config (.pc) files, xbuild additionally
 184 looks in "/Library/Frameworks/Mono.framework/External/pkgconfig" .
 185
 186 .SH SEE ALSO
 187 .BR mono(1), mcs(1)
 188 .SH COPYRIGHT
 189 Copyright (C) 2011 Novell, Inc (http://www.novell.com)
 190 .SH MAILING LISTS
 191 Visit http://lists.ximian.com/mailman/listinfo/mono-devel-list for details.
 192 .SH WEB SITE
 193 Visit: http://www.mono-project.com for details