Using MSBuild - incorrect paths for MRefBuilder

Topics: Bugs, General Questions, Sandcastle
Aug 14, 2007 at 6:51 PM
I've configured DocProject in my solution and have it referencing all my other projects. When building inside Visual Studio, everything works great and the docs are all generated (still get some unknown reference links, but that's another issue).

However, when I try to use MSBuild to build, I get errors on the MREfBuilder step where paths could not be found. It seems like the difference is that in Visual Studio, it is picking up the output path from each of the projects when formulating the dependency list of the MREFBuilder command. However, when just running MSBuild against the DocProject, it doesn't use those output paths. Is there any way to get it to reference the correct paths?
Coordinator
Aug 14, 2007 at 7:56 PM
Hi,

When running outside of VS, DocProject gets the paths to source projects straight from your DocProject's or DocSite's project file by examining all of the <ProjectReference> items. If you take a look at the MRefBuilder command in the build trace, what paths appear to be used in the list of source projects? (Be aware that the dependency list is separated by commas, and then the source list follows with each source assembly separated by spaces).

Are the source paths correct?

DocProject discovers the dependency information of each source project by loading the assembly from the paths that you see here, so if the paths are correct then there must be some other reason why DocProject cannot discover the dependency information automatically.

Can you build the project using the DocProject External UI?

Just FYI, the external UI uses MSBuild internally and you may find it easier to work with than the command-line.

- Dave
Aug 14, 2007 at 8:40 PM
Hi Dave,
Thanks for the info. It appears the source paths are correct from within Visual Studio, but not from the command line running MSBuild. I just tried to build using the DocProject External UI and that works as well and also has the correct source paths. So one of the correct source paths looks like:

"C:\cc\dev\alpha\Framework\Source\Infrastructure\Infrastructure.Interface\..\..\..\bin\Debug\Infrastructure.Interface.dll"

Note that in my output path for the project, I specified a relative path up 3 levels to make sure everything gets dumped into a common directory

When I run msbuild from the command line against the DocProject (e.g. msbuild frameworkDoc.csproj)
"C:\cc\dev\alpha\Framework\Source\Infrastructure\Infrastructure.Interface\bin\Debug\Infrastructure.Interface.dll"

The reason I'm trying to use MSBuild is because I want to incorporate it into my automated msbuild script.

BTW, I've been looking across the internet for options to work with Sandcastle and this is an absolutely fantastic project!
Coordinator
Aug 14, 2007 at 9:21 PM
Edited Aug 14, 2007 at 9:21 PM
Hi,

I can't reproduce this issue. Using MSBuild on the command-line seems to work just fine for me.

If you want to send me a zip of your solution I'll take a look. My email is Dave-a_t-davesexton-d_o_t-com.

Thanks for the feedback,
Dave
Aug 14, 2007 at 9:51 PM
Dave,
I just created a very simple solution that recreates the problem. I'll send it over. Just to be clear, when I run from the command line, I change into the directory with the DocProject csproj file and just type "msbuild ProjectX.csproj" where ProjectX.csproj is the name of the project file. Is that correct?
Coordinator
Aug 14, 2007 at 11:31 PM
That's correct.

BTW, I'm taking a look at the project now - I'll get back to you.

Thanks,
Dave
Coordinator
Aug 15, 2007 at 12:08 AM
Edited Aug 15, 2007 at 12:14 AM
I had to change the <DocumentationFile> path to (EDIT: ..\out\debug\DocTest.XML) to get it to build since it was hard-coded to a path that doesn't exist on my computer, but then when I built the project I did see that the MRefBuilder command contained the wrong path:

MRefBuilder /config:"C:\Projects\DocTest\ProjectDocumentation1\Presentation\Style\Configuration\MRefBuilder.config" 
  /out:reflection.org /internal- "C:\Projects\DocTest\DocTest\bin\Debug\DocTest.dll"
The source path should have been C:\Projects\DocTest\out\debug\DocTest.dll.

If you're using DocProject 1.7.0 then the problem may be caused by a change I made to the MSBuildProjectOutput class to support Team Build. The output path is now taken from MSBuild's OutDir property instead of the project's OutputPath property.

It seems that you can solve this issue by overriding the OutDir property and specifying the appropriate path. Try this:

cd "C:\Projects\DocTest\ProjectDocumentation1"
msbuild /property:OutDir=..\out\debug\ ProjectDocumentation1.csproj

Does that help?

- Dave
Aug 15, 2007 at 12:37 AM
Thanks! Yes, I am using 1.7.0 and that definitely did the trick. I'm not too keen on having to hard code the project's output path here, but I can probably work it somehow. At least it works now!
Coordinator
Aug 15, 2007 at 1:07 AM
I'm glad it works.

I'll investigate this further and see if it's possible for DocProject to work with custom output paths and Team Build simultaneously for 1.8.0.

Thanks for the reply,
Dave
Aug 15, 2007 at 9:24 PM
Looks like I spoke too soon. While the small sample project I created works fine, my actual project doesn't. My solution contains multiple projects and there are dependencies. From what I can gather, the build process for the DocProject goes through a number of steps of actually building the referenced projects (if needed) and does some copying of the items. However, one of the steps called:

Target IncrementalClean deletes files from the Ouput directory (how referenced I'm not sure).

When OutDir is set to be the same as the project's OutputPath, it seems like what happens is my built assembly will get copied to the same directory, and then it gets deleted. Subsequently, any additional things that relied on this DLL now fail.

I'll play around with this some more. Maybe the solution is for me to make a special build of DocProject and revert the change that was made in the MSBuildProjectOutput class to leave OutDir alone?
Coordinator
Aug 16, 2007 at 7:08 AM
Hi,

Sorry for the delay in my response. For some reason all of the posts in this thread are jumbled up, so I thought I'd wait until it was fixed by CodePlex. It's still not fixed, but I just clicked Reply on what I think was your latest post to see what happens anyway :) Are the order of the posts messed up for you too?


Looks like I spoke too soon. While the small sample project I created works fine, my actual project doesn't. My solution contains multiple projects and there are dependencies. From what I can gather, the build process for the DocProject goes through a number of steps of actually building the referenced projects (if needed) and does some copying of the items.

Actually MSBuild does that, not DocProject.


However, one of the steps called:

Target IncrementalClean deletes files from the Ouput directory (how referenced I'm not sure).

DocProject isn't calling that target, so it must be a Visual Studio target. I'm not sure what its purpose is though.


When OutDir is set to be the same as the project's OutputPath, it seems like what happens is my built assembly will get copied to the same directory, and then it gets deleted. Subsequently, any additional things that relied on this DLL now fail.

I guess the change you've made to the project files doesn't allow you to specify OutDir as well. Maybe this is just a problem with Visual Studio project files in general. I guess this works without using a DocProject though, correct?


I'll play around with this some more. Maybe the solution is for me to make a special build of DocProject and revert the change that was made in the MSBuildProjectOutput class to leave OutDir alone?

You could certainly try that but I'd much rather figure out a solution that I can include in 1.8.0 that will work with Team Build as well, of course.

For help see How To Use The Source Code. If you need further assisstance please ask.

Thanks,
Dave
Aug 16, 2007 at 6:00 PM

davedev wrote:
Hi,

Sorry for the delay in my response. For some reason all of the posts in this thread are jumbled up, so I thought I'd wait until it was fixed by CodePlex. It's still not fixed, but I just clicked Reply on what I think was your latest post to see what happens anyway :) Are the order of the posts messed up for you too?

Yes, they are messed up for me too. It wasn't like that yesterday... it appears all of your posts are at the top and all of mine are at the bottom.


I guess the change you've made to the project files doesn't allow you to specify OutDir as well. Maybe this is just a problem with Visual Studio project files in general. I guess this works without using a DocProject though, correct?

Yes, the project files worked fine without using the DocProject, both from within Visual Studio and called from command line using MSBuild.


I'll play around with this some more. Maybe the solution is for me to make a special build of DocProject and revert the change that was made in the MSBuildProjectOutput class to leave OutDir alone?

You could certainly try that but I'd much rather figure out a solution that I can include in 1.8.0 that will work with Team Build as well, of course.

So just to let you know, I went ahead and rebuilt DocProject and reverted the change that you made in MSBuildProjectOutput to see if that would help. And it does. I have been able to successfully build using msbuild at the command-line. I can try to continue to look at this a little more to see if there is a solution that accommodates Team Build. I just need to get a better handle of all the targets that are being run and when OutDir is referenced as opposed to OutputPath.
Coordinator
Aug 16, 2007 at 8:15 PM
Edited Aug 16, 2007 at 8:16 PM
You might want to vote on the sorting issue that I posted to CodePlex: http://www.codeplex.com/CodePlex/WorkItem/View.aspx?WorkItemId=12278

I'm glad that you were able to rebuild the source code successfully. It's a shame that I currently have to choose between support for custom output paths and Team Build. I'm actually not certain at this point that there's a way to support both simultaneously.

I have a thread about support for Team Build in Microsoft's forums. You may want to monitor it for responses as well:

http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=2006773&SiteID=1

(It appears that there's a new post, which I haven't read yet myself...)

If I think of anything else I'll let you know

Thanks,
Dave
Coordinator
Aug 18, 2007 at 12:06 AM
Hi,

Just FYI, I believe that I've determined the cause and now I'm just waiting for a response:

http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=2006773&SiteID=1

The cause appears to be that OutDir is being used to support Team Build, which sets it globally, but it's also being used when it's evaluated (not global). The output paths that you've set in your project files are not being used because the OutputPath in your DocProject is being used instead as the evaluated value for OutDir.

Thanks,
Dave
Coordinator
Aug 27, 2007 at 1:42 PM
Hi,

I think I've finally solved your problem with the help of Aaron's suggestion from the forums thread that I cited in a previous response. If you have the time I'd appreciate it if you could test the updates.

You can download a .zip file that contains the changes I've made and patch the solution by simply replacing the files with the updated copies. Please make sure that you either overwrite the .targets file in DocProject's installed bin directory or if you plan on rebuilding the installer, then update the .targets file in the InstallPrep project. If you need more help locating files please let me know. Also, more information can be found in that Microsoft forums thread.

Updated .zip file attached to work item: Team Build

Thanks,
Dave
Aug 27, 2007 at 9:19 PM

davedev wrote:
Hi,

I think I've finally solved your problem with the help of Aaron's suggestion from the forums thread that I cited in a previous response. If you have the time I'd appreciate it if you could test the updates.

You can download a .zip file that contains the changes I've made and patch the solution by simply replacing the files with the updated copies. Please make sure that you either overwrite the .targets file in DocProject's installed bin directory or if you plan on rebuilding the installer, then update the .targets file in the InstallPrep project. If you need more help locating files please let me know. Also, more information can be found in that Microsoft forums thread.

Updated .zip file attached to work item: Team Build

Thanks,
Dave


Thanks Dave. I'll try to test it out when I get a chance.
Aug 30, 2007 at 6:57 PM
Dave,
Just to report back, I tested out your latest changes on my project and it appears to work fine from the command line. I'll do some more testing, but so far so good. Thanks!

Jimmy
Coordinator
Aug 30, 2007 at 7:37 PM
Great Jimmy, thanks. That's good enough for me... I'll merge the changes into 1.8.0. Of course, if you continue testing and run into any issues please let me know :)

- Dave
Aug 30, 2007 at 9:01 PM
Just read this post. Excellent news that 1.8.0 is on its way.

Regards,
Kurt