From ed5561702f6d1e93b0c4580ce0bd8dcc3fe7b3a1 Mon Sep 17 00:00:00 2001 From: Christoph Ruegg Date: Mon, 27 Apr 2020 13:28:17 +0200 Subject: [PATCH] Docs: update build documentation with more on how to build MKL on Windows --- LICENSE.md | 2 +- MathNet.Numerics.sln | 37 ++++++++++++++++++ docs/content/Build.md | 89 ++++++++++++++++++++++--------------------- 3 files changed, 83 insertions(+), 45 deletions(-) diff --git a/LICENSE.md b/LICENSE.md index cd1ac9ed..14c428e8 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,7 +1,7 @@ Math.NET Numerics License (MIT/X11) =================================== -Copyright (c) 2002-2019 Math.NET +Copyright (c) 2002-2020 Math.NET Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation diff --git a/MathNet.Numerics.sln b/MathNet.Numerics.sln index 76f14465..7586908b 100644 --- a/MathNet.Numerics.sln +++ b/MathNet.Numerics.sln @@ -41,6 +41,43 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "TestData", "src\TestData\Te EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Benchmark", "src\Benchmark\Benchmark.csproj", "{82444930-9FD7-41B6-B476-CCE41A0C0A0B}" EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Docs", "Docs", "{B890C1AF-E488-490F-B784-2C6F8C924693}" +ProjectSection(SolutionItems) = preProject + docs\content\Build.md = docs\content\Build.md + docs\content\Compatibility.md = docs\content\Compatibility.md + docs\content\Constants.md = docs\content\Constants.md + docs\content\CSV.md = docs\content\CSV.md + docs\content\DescriptiveStatistics.md = docs\content\DescriptiveStatistics.md + docs\content\Distance.md = docs\content\Distance.md + docs\content\Euclid.md = docs\content\Euclid.md + docs\content\Functions.md = docs\content\Functions.md + docs\content\Generate.md = docs\content\Generate.md + docs\content\IFsharpNotebook.md = docs\content\IFsharpNotebook.md + docs\content\index.md = docs\content\index.md + docs\content\IntegralTransforms.md = docs\content\IntegralTransforms.md + docs\content\Integration.md = docs\content\Integration.md + docs\content\Interpolation.md = docs\content\Interpolation.md + docs\content\LinearEquations.md = docs\content\LinearEquations.md + docs\content\MatlabFiles.md = docs\content\MatlabFiles.md + docs\content\Matrix.md = docs\content\Matrix.md + docs\content\MatrixMarket.md = docs\content\MatrixMarket.md + docs\content\MKL.md = docs\content\MKL.md + docs\content\Packages.md = docs\content\Packages.md + docs\content\Probability.md = docs\content\Probability.md + docs\content\Random.md = docs\content\Random.md + docs\content\Regression.md = docs\content\Regression.md + docs\content\Users.md = docs\content\Users.md + CONTRIBUTING.md = CONTRIBUTING.md + CONTRIBUTORS.md = CONTRIBUTORS.md + README.md = README.md + RELEASENOTES.md = RELEASENOTES.md + RELEASENOTES-CUDA.md = RELEASENOTES-CUDA.md + RELEASENOTES-Data.md = RELEASENOTES-Data.md + RELEASENOTES-MKL.md = RELEASENOTES-MKL.md + RELEASENOTES-OpenBLAS.md = RELEASENOTES-OpenBLAS.md + LICENSE.md = LICENSE.md +EndProjectSection +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU diff --git a/docs/content/Build.md b/docs/content/Build.md index b8c0f906..00f4e7fe 100644 --- a/docs/content/Build.md +++ b/docs/content/Build.md @@ -15,18 +15,17 @@ may fail to compile or provide correct IntelliSense. Tests can be run with the usual integrated NUnit test runners or ReSharper. -MSBuild or XBuild ------------------ +Command Line Tools +------------------ Instead of a compatible IDE you can also build the solutions directly with -`msbuild`, or on Mono with `xbuild`. You may need to run `restore.cmd` or +the .NET Core SDK, with MsBuild or on Mono with XBuild. You may need to run `restore.cmd` or `restore.sh` before, once after every git checkout in order to restore the dependencies. restore.cmd (or restore.sh) # restore dependencies (once) - msbuild MathNet.Numerics.sln # only build for .Net 4 (main solution) - msbuild MathNet.Numerics.Net35Only.sln # only build for .Net 3.5 - msbuild MathNet.Numerics.All.sln # full build with .Net 4, 3.5 and PCL profiles - xbuild MathNet.Numerics.sln # build with Mono, e.g. on Linux or Mac + dotnet build MathNet.Numerics.sln # with .NET Core SDK + msbuild MathNet.Numerics.sln # with MsBuild + xbuild MathNet.Numerics.sln # with Mono FAKE ---- @@ -38,29 +37,20 @@ FAKE itself is not included in the repository but it will download and bootstrap itself automatically when build.cmd is run the first time. Note that this step is *not* required when using Visual Studio or `msbuild` directly. - build.cmd # normal build (.Net 4.0), run unit tests (.Net on Windows) - ./build.sh # normal build (.Net 4.0), run unit tests (Mono on Linux/Mac, .Net on Windows) - - build.cmd Build # normal build (.Net 4.0) - build.cmd Build incremental # normal build, incremental (.Net 4.0) - build.cmd Build all # full build (.Net 4.0, 3.5, PCL) - build.cmd Build net35 # compatibility build (.Net 3.5 - build.cmd Build signed # normal build, signed/strong named (.Net 4.0) + ./build.sh # normal build and unit tests, when using bash shell on Windows or Linux. + build.cmd # normal build and unit tests, when using Windows CMD shell. - build.cmd Test # normal build (.Net 4.0), run unit tests - build.cmd Test quick # normal build (.Net 4.0), run unit tests except long running ones - build.cmd Test all # full build (.Net 4.0, 3.5, PCL), run all unit tests - build.cmd Test net35 # compatibility build (.Net 3.5), run unit tests + ./build.sh build # normal build + ./build.sh build strongname # normal build and also build strong named variant - build.cmd Clean # cleanup build artifacts - build.cmd Docs # generate documentation - build.cmd Api # generate api reference - build.cmd Zip # generate zip packages (.Net 4.0) - build.cmd NuGet # generate NuGet packages (.Net 4.0) - build.cmd NuGet all # generate normal NuGet packages (.Net 4.0, 3.5, PCL) - build.cmd NuGet signed # generate signed/strong named NuGet packages (.Net 4.0) + ./build.sh test # normal build (.Net 4.0), run unit tests + ./build.sh test quick # normal build (.Net 4.0), run unit tests except long running ones - build.cmd All # build, test, docs, api reference (.Net 4.0) + ./build.sh clean # cleanup build artifacts + ./build.sh docs # generate documentation + ./build.sh api # generate api reference + + ./build.sh all # build, test, docs, api reference If the build or tests fail claiming that FSharp.Core was not be found, see [fsharp.org](https://fsharp.org/use/windows/) or install the @@ -73,12 +63,11 @@ We manage NuGet and other dependencies with [Paket](https://fsprojects.github.io You do not normally have to do anything with Paket as it is integrated into our FAKE build tools, unless you want to actively manage the dependencies. -You can bootstrap or update Paket by calling `tools/paket/paket.bootstrapper.exe`. -After bootstrapping, `tools/paket/paket.exe restore` will restore the packages +`.paket/paket.exe restore` will restore the packages to the exact version specified in the `paket.lock` file, -`tools/paket/paket.exe install` will install or migrate packages after you have -made changes to the `paket.dependencies` file, `tools/paket/paket.exe outdated` -will show whether any packages are out of date and `tools/paket/paket.exe update` +`.paket/paket.exe install` will install or migrate packages after you have +made changes to the `paket.dependencies` file, `.paket/paket.exe outdated` +will show whether any packages are out of date and `.paket/paket.exe update` will update all packages within the defined constraints. Have a look at the Paket website for more commands and details. @@ -88,7 +77,7 @@ Documentation This website and documentation is automatically generated from of a set of [CommonMark](https://commonmark.org/) structured files in `doc/content/` using [FSharp.Formatting](https://tpetricek.github.io/FSharp.Formatting/). -The final documentation can be built by calling `build.sh Docs`. +The final documentation can be built by calling `build.sh docs`. However, for editing and previewing the docs on your local machine it is more convenient to run `build.sh DocsWatch` in a separate console instead, which @@ -112,9 +101,7 @@ to the assembly info files automatically. The build can then be launched by calling: - build.sh All release # full release build - build.sh NuGet release # if you only need NuGet packages - build.sh Zip release # if you only need Zip packages + ./build.sh all The build script will print the current version as part of the the header banner, which is also included in the release notes document in the build artifacts. @@ -140,13 +127,30 @@ Extra Packages -------------- In addition to the core package this repository also include extra packages -like the MKL provider and the data extensions. Most build targets are available for +like the data extensions. Most build targets are available for these packages as well, with the following prefixes: -* `Mkl` for the MKL provider (`MklWin` or `MklLinux` if platform dependent) * `Data` for the Data Extensions -Example: `build.sh MklWinNuget release` +Example: `build.sh DataBuild` + +Intel MKL on Windows +-------------------- + +The build expects that either Intel Parallel Studio 2020 (with the Intel Compiler) +or Intel Math Kernel Library 2020 is installed. If you run into an error with `mkl_link_tool.exe` +you may need to patch a targets file, see [MKL 2020.1, VS2019 linking bug ](https://software.intel.com/en-us/forums/intel-math-kernel-library/topic/851578). + +The build can then be triggered by calling: + + ./build.sh MklWinBuild // build both 32 and 64 bit variants + ./build.sh MklTest // run all tests with the MKL provider enforced + ./build.sh MklWinAll // build and run tests + +The build puts the binaries to `out/MKL/Windows/x64` (and `x86`), the NuGet package +to `out/MKL/NuGet` and a Zip archive to `out/MKL/Zip`. You can directly use the provider from +there by setting `Control.NativeProviderPath` to the full path pointing to `out/MKL/Windows/`; +this is also what the unit tests do when you run the `MklTest` build target. Official Release Process (Maintainers only) ------------------------------------------- @@ -156,7 +160,7 @@ Official Release Process (Maintainers only) * Build Release: - build.sh All release + build.sh all strongname * Commit and push release notes and (auto-updated) assembly info files with new "Release: v1.2.3" commit @@ -165,12 +169,9 @@ Official Release Process (Maintainers only) build.sh PublishDocs build.sh PublishApi build.sh PublishTag - build.sh PublishMirrors + build.sh PublishArchive build.sh PublishNuGet - In theory there is also a `Publish` target to do this in one step, unfortunately - publishing to the NuGet gallery is quite unreliable. - * Consider a tweet via [@MathDotNet](https://twitter.com/MathDotNet) * Update Wikipedia release version and date for the [Math.NET Numerics](https://en.wikipedia.org/wiki/Math.NET_Numerics) and