Command line builds - what goes in solution file

Topics: User Forum
Oct 29, 2009 at 4:25 AM


I've upgraded from Sandcastle version 1.6 to Beta and am working on getting my documentation to build again.

Documentation gets built from the command line.  With version 1.6,  after some work I was able to build using SandCastleConsoleBuild.exe.  In, SandCastleConsoleBuild.exe is gone - sounds like a good idea.  Now, I have absolutely no idea what to put into a project file for MSBuild.exe to look at.   For someone not familiar with MSBuild, pages like are difficult to follow.  There is a lot of undefined terminology there.  I am looking for a simple example of what goes into the project file (HelpFile.shfbproj?) in order to build documentation for one DLL.  Any help would be appreciated.  Thanks.

Oct 29, 2009 at 3:21 PM

The simplest approach is to use the GUI to create the project.  It manages the project for you.  You can also use it to add items to the project to see how the elements are formatted if you want to create target override files.  If you have more specific questions about building from the command line, you can ask here.



Oct 29, 2009 at 5:32 PM

All right.  I will make suggestions as I go along, so that you can know where I got stuck and make things easier in the product for the next person.


First problem:


[Sandcastle Help File Builder Utilities, version]

Creating output and working folders...


Clearing working folder...


Finding tools...

Last step completed in 00:00:00.0000


SHFB: Error BE0065: BUILD FAILED: The given path's format is not supported.



The  description at says:


This is the generic error produced when a build fails for an unexpected reason.


Review the build log output just prior to the point of this error and look for other error or warning messages that may have contributed to the problem. If you cannot resolve the problem, please post a message in the Sandcastle Help File Builder discussion forum asking for help along with the details from the build log.


I'm not sure what path is being referred to here.  Suggestion: display the path name in question.  As of now I have no idea what the problem is.  I set up a project, added a DLL and three .xml files through the Add Document Source menu.

Oct 29, 2009 at 6:29 PM
Edited Oct 29, 2009 at 7:12 PM

Another question.  The installation instructions list what is required in order to build help files.  I want to build html files, not help files.  Do I still need to install the 100+ megabyte Visual Studio SDK and the other things listed in that section?  I sure hope the answer to this is "no," because first I would prefer not to have to clutter my machine with yet more installed software, and second, I cannot install the Visual Studio SDK.  I do not have Visual Studio, and the Visual Studio SDK installation script is telling me that I need Visual Studio 2008 SP1 or greater in order to install the Visual Studio SDK.  This wasn't required in earlier Sandcastle versions.

Suggestion: clarify this in the installation instructions.

Oct 29, 2009 at 7:35 PM

Regarding the path error, it's in the Finding Tools step so it's either the path to Sandcastle, the Help 1 compiler, or the Help 2 compiler.  I'd say it's the SandcastlePath property since that's the first tool it looks for and there's no message stating that it found it.  If you haven't set it explicitly, then it's probably an error in the value stored in the DXROOT environment variable.  If you've just installed everything, try rebooting as sometimes it takes a reboot for the environment variable to get picked up.

If by "HTML files", you mean website output (HelpFileFormat = Website), then no you don't need the VS SDK.  You only need the SDK if you plan on build Help 2 (HxS) files since the Help 2 compiler is only distributed as part of it.  If you don't plan on building CHM files, you can ignore the Help 1 compiler too.  The stuff in the Recommended Additions and Optional Items sections are just that: recommended and optional.  Install them if you want, otherwise ignore them.



Oct 29, 2009 at 7:41 PM

Thanks.  It was a problem with the DXOOT environment variable and PATH environment variables.

I am glad to hear that I will not need Visual Studio to generate HTML output.

There is a dependency not mentioned in the installation instructions: the need to upgrade to a sufficiently new version of Sandcastle.  Suggestion: mention this in the installation instructions.