Skip to content

Stop the F# wrapper hardcoding its documentation path - #889

Merged
Rafael-SOWNet merged 1 commit into
masterfrom
fix/fsharp-doc-path
Aug 11, 2026
Merged

Stop the F# wrapper hardcoding its documentation path#889
Rafael-SOWNet merged 1 commit into
masterfrom
fix/fsharp-doc-path

Conversation

@Rafael-SOWNet

Copy link
Copy Markdown
Collaborator

dotnet build -c release — lowercase — cannot build AngouriMath.FSharp from a clean checkout on
Linux or macOS:

FSC : error FS0193: Could not find a part of the path
'.../Sources/Wrappers/AngouriMath.FSharp/bin/Release/netstandard2.0/AngouriMath.FSharp.XML'

Cause

The fsproj set the documentation path literally:

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
  <DocumentationFile>bin\Release\netstandard2.0\AngouriMath.FSharp.XML</DocumentationFile>
</PropertyGroup>

MSBuild compares strings in a Condition case-insensitively, so with -c release the condition
matches and DocumentationFile points at bin/Release/…. But $(OutputPath) is built from the
configuration as spelled, so the directory that actually gets created is bin/release/. On a
case-sensitive filesystem those are two different paths, the second does not exist, and the F#
compiler cannot create the file in it.

Fix

<GenerateDocumentationFile>true</GenerateDocumentationFile>, which puts the XML beside the
assembly whichever way the configuration is spelled and needs no path. AngouriMath.Terminal.Lib
already does exactly this, so it is the in-repo precedent rather than a new idea. The main library
was never affected — it uses bin/$(Configuration)/$(TargetFramework)/…, which follows the spelling.
AngouriMath.FSharp was the only project with a literal.

Verified from a clean bin and obj, both spellings

dotnet test -c release 130 passed, 0 failed — this is the command that used to fail
dotnet build -c Release succeeds, and still produces AngouriMath.FSharp.xml and AngouriMath.FSharp.2.0.0.nupkg

So packaging is unchanged; the only difference is that the file is now .xml rather than .XML,
which is what every other project here already emits.

Why nobody hit it

-c Release works, and -c release also works once a capitalised build has created the
directory
. It fails only on a clean checkout that has never been built with the capitalised
spelling — which is what CI would do if it ever used the lowercase form, and what I did while
measuring #888. It cost a measurement I had to redo: the first run reported the F# suite as having
been exercised when the build had in fact failed, which is the trap in
dotnet test reusing whatever assembly is already there.

`dotnet build -c release` -- lowercase -- could not build AngouriMath.FSharp from clean
on a case-sensitive filesystem:

    FSC : error FS0193: Could not find a part of the path
    '.../AngouriMath.FSharp/bin/Release/netstandard2.0/AngouriMath.FSharp.XML'

The fsproj set DocumentationFile to a literal bin\Release\... under a condition on
'$(Configuration)|$(Platform)'=='Release|AnyCPU'. MSBuild compares that
case-insensitively, so with -c release the condition matched and the doc file was
directed at bin/Release/ while $(OutputPath) resolved to bin/release/ -- a directory
that does not exist on Linux or macOS, and the compiler cannot create the file in it.

GenerateDocumentationFile puts the XML beside the assembly whichever way the
configuration is spelled, and needs no path at all. AngouriMath.Terminal.Lib already
does it this way; the main library uses $(Configuration) in its path, so neither was
affected.

Why it went unnoticed: -c Release works, and so does -c release once a capitalised build
has created the directory, so it only fails on a clean checkout that never used the
capitalised spelling.

Verified both spellings from a clean bin and obj: 130 F# tests pass under -c release, and
under -c Release the build still produces AngouriMath.FSharp.xml and the .nupkg.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant