EWSoftware
Linux/Docker builds
First off, thank you so much for making this. I've been using it for years and it's been great.
Recently I've been going down the path of documenting one of my frameworks and setting up build infrastructure for projects that may use it. To that end, I decided to do a kestrel hosted (static files) site, using it to host the SHFB generated help content - using a Linux Docker container.
It's a .NET 8 application, so I included the regular tools package as well as the .NET 5+ package in the shfbproj and set the relevant MSBuild properties to leverage those tools to do the build. In my multistage build, I do a dotnet build of the projects that contain the XML-Doc, followed by a build of the shfbproj, before building the hosting app that links the actual site content it.
The shfbproj build fails on Linux, but succeeds on Windows. This appears to be for a few reasons:
- pathing for non-windows platforms doesn't appear to be handled consistently (looking for the index of or appending \ in a number of places rather than the platform directory separator character)
- calculation of the base path for the XML documentation files is assumed to be relative to OutDir rather than the project file
- determining the build process incorrectly (assuming the dotnet executable will have an exe extension, where it doesn't on non-Windows)
- relying on netfx 4.8 when generating the project file for the mrefbuilder (a nuget package can be added to the project to make this work - making the required reference assemblies for the build available)
- p/invoke targeting Windows DLLs used when processing the reference assemblies (for GAC access and memory mapped files)
I pulled down the source over the weekend and have worked though all but the p/invoke dependence so far. Would you be open to a pull request to absorb some or all of these?
Posted a draft with at least as much as is required to get my project building under Linux. I've left myself a bunch of cleanup comments, but it should be enough to go on to get a feel for whether the type of changes are desirable
Unfortunately, I have no way of testing and supporting a Linux build so it isn't something I could support or fix if future changes broke it. If these changes require a separate distribution specific to Linux, it's also something I cannot support for the same reason. I have some concern with some of the changes as well. It looks like you just ripped out the code related to the OutDir project path. While that may get it working for you, I suspect it will break it for others that currently depend on the behavior under Windows. Such changes should likely be conditional on the variable not being there or something platform-specific so that it would work in either case. Making significant changes to MRefBuilder like removing memory mapped files may introduce issues with performance and memory usage in projects with large numbers of assemblies being processed such as when generating the reflection data files for a framework. This may be something that works better as a Linux-specific fork.
All definitely fair points, thanks for taking the time to look over it.
I'm working on bringing the memory mapped files stuff back - conditionally skipping it for non-Windows platforms, but had temporarily removed it since the moment those classes get initialized the P/Invoke started causing issues. Was mainly trying to just get myself a checkpoint where things were working for me locally.
The OutDir bit I'd have to revisit, but DocumentationFile (ex. value bin\$(Configuration)\$(TargetFramework)\$(MSBuildProjectName).xml) ends up being relative to the project file's directory, rather than OutDir on both Windows and Linux, at least for SDK style projects.
As far as a Linux specific fork goes, I'm not necessarily opposed to doing that, but also don't want to distract from all the great work you've put in here or add confusion with a different, but similar, build tools package.
Turns out that OutDir is happening to evaluate to the project directory, so I've restored that. Also brought back the memory mapped files, with non-Windows degrading to just loading the files in to buffers.
Proposed changes should be much lower risk now, if that makes the change any more palatable