Update README.md

README.md

@@ -1,6 +1,14 @@
-## The goal of aardvark.build
+# Aardvark.Build
 
-Before aardvark.build we had dozens of projects with custom build scripts based on fake (and aardvark.fake - some additional commonly used utilities).
+![Publish](https://github.com/aardvark-platform/aardvark.build/workflows/Publish/badge.svg)
+[![NuGet](https://badgen.net/nuget/v/Aardvark.Build)](https://www.nuget.org/packages/Aardvark.Build/)
+[![NuGet](https://badgen.net/nuget/dt/Aardvark.Build)](https://www.nuget.org/packages/Aardvark.Build/)
+
+Build tools for the Aardvark platform.
+
+## The goal of Aardvark.Build
+
+Before Aardvark.Build we had dozens of projects with custom build scripts based on fake (and Aardvark.Fake - some additional commonly used utilities).
 We often had problems maintaining those.
 In order to remove as much code as possible, this msbuild task & assembly provides features such as:
  * parsing release notes
@@ -10,24 +18,78 @@ In order to remove as much code as possible, this msbuild task & assembly provid
  * automatic patching of assembly version (e.g. 1.2.3 ~> 1.2.0)
  * creating packages, creating tags, github releases and uploading packages
 
-
 There are two components:
- * the msbuild targets file - Aardvark.Build.targets and the accompanying assembly aardvark.build: works on an assembly level and prepares the assembly by, injecting native libs, patching the assembly version etc etc.
+ * the MSBuild targets file - Aardvark.Build.targets and the accompanying assembly Aardvark.Build: works on an assembly level and prepares the assembly by, injecting native libs, patching the assembly version etc etc.
  * the aardpack dotnet tool: builds a package and packs it into a .nupgk using paket, creates tags and so on.
 
-## For Users
+## Release Notes & Versions
 
-Documentation on usage is in ./docs.
-
-## For maintainers
+Aardvark.Build expects your project to have a file called `RELEASE_NOTES.md` (case insensitive and also allowing some variations of the name) in the repository-root directory. This file will be used to get `AssemblyVersion` and also `PackageVersion` during build/pack. The syntax for the file sticks to the one defined by `Fake.Core.ReleaseNotes` and may for example look like:
 
-Some things to remember when working on the project or when fixing bugs:
+```markdown
+### 0.1.2.3
+- fixed problem 1
+- added feature XY
 
- * Aardvark.Build.dll needs to be robust. Often it runs within msbuild executions, thus the environment it runs in cannot be specified. Unfortunately, we cannot use isolated dotnet environments to make assembly loading robust in this scenario (msbuild uses net48). This is particularly problematic when using third party libs in the lib referenced by the targets file. To be robust to different assembly versions (often fsharp.core) being already loaded when the tool is invoked we register `AssemblyResolveEventHandle`s in ./Aardvark.Build/Utilities.fs. As long as there are no isolated environments we cannot reference utility libraries in the build task since already loaded libraries could prevent the runtime from loading them leading to missing method exceptions. For example for parsing release notes we copied the FAKE code over in order to prevent dependency problems.
- * aardvark.build.fsproj references ```  <Import Project="..\bin\Debug\netstandard2.0\Aardvark.Build.targets" Condition="'$(Configuration)' == 'Release' AND Exists('..\bin\Debug\netstandard2.0\Aardvark.Build.targets')" />``` itself for handling its packaing. Multiple builds in build.sh|build.cmd make this possible.
- * Always make sure to test everything using the ./Test project which references the target file compiled using pack.sh|pack.cmd
-
-
-## Credits
+### 0.1.2.3-alpha01
+- some changes
+```
+
+The latest (highest) version in this file will be used for creating packages via `dotnet pack` and also determines the `AssemblyVersion` for resulting DLLs. Since `AssemblyVersion` cannot handle *prerelease-suffixes* and in order to be fully compliant to **SemVer** the `AssemblyVersion` will only include the first two digits of the package-version (this way SemVer-compatible dlls can be interchanged at runtime without dotnet complaining). For example a PackageVersion `1.2.3.4-alpha01` will result in AssemblyVersion `1.2.0.0`.
+
+The build process also includes the full PackageVersion in the resulting DLLs as `AssemblyInformationalVersion` which can easily be queried during runtime (for example for logging, etc.)
+
+## Native Dependencies
+
+Aardvark embeds native dependencies into the DLLs. These dependencies are extracted to a special directory in `LocalApplicationData` during `Aardvark.Init()` s.t. they can be loaded at runtime.
+
+In order to add native dependencies to your DLL you just need to create a directory-structure in your repository-root like `<root>/libs/Native/<ManagedDllName>/<Platform>/<Architecture>/` that contains the desired files with these possible values for `<Platform>` and `<Architecture>`:
+
+| `<Platform>`  |
+| ------------- |
+| `mac/`        |
+| `linux/`      |
+| `windows/`    |
+
+| `<Architecture>`  |
+| ----------------- |
+| `AMD64`           |
+| `x86`             |
+| `ARM64`           |
+
+Please note that the `<ManagedDllName>` needs to be the `AssemblyName` of your project (excluding the `.dll` extension). For example `MyLib.dll` needs a subfolder `MyLib`. Also note that all strings are **case-sensitive**.
+
+Currently `Aardvark.Build` may run into problems when your `AssemblyName` is not the same as the project-file-name so for the moment we recommend sticking to default `AssemblyName`s.
+
+## Packaging
+
+Aardvark.Build expects your project to use `paket` for managing dependencies and several parts of it may not work correctly without it.
+
+If you want to create a package for a project you will need to place a `paket.template` file next to the `.(c|f)sproj` with standard paket behaviour.
+
+We *replace* the standard behaviour of `dotnet pack` with `paket pack` using appropriate version/release-notes.
+
+## Local Source Packages
+
+Aardvark.Build allows you to use locally-built packages that **override** nuget-dependencies. This is especially useful for testing things across multiple repositories and debugging.
+
+For adding an external repository you need to create a file called `local.sources` in your repository-root that holds the source-project's path and build/pack commands. A little example:
+
+```
+/home/dev/myrepo
+    dotnet build
+    dotnet pack -o {OUTPUT}
+
+/home/dev/otherrepo
+    dotnet tool restore
+    dotnet build MyProj/MyProj.fsproj
+    dotnet paket pack {OUTPUT}
+```
+
+Non-indented strings are interpreted as paths to the repository (absolute or relative to the .sources file) and all indented lines following are commands that create packages in the spliced folder-path `{OUTPUT}` provided by Aardvark.Build. 
+
+All packages created this way will override their nuget/paket counterparts during build and startup. However we experienced some problems with auto-completion for newly added functions, etc.
+
+Since building projects can be costly we reuse the packages whenever the source is unchanged. For this caching to work best it is strongly recommended that you use git-repositories as sources. It will work on non-git directories but might trigger rebuilds too often.
 
-We use portions of FAKE for parsing release notes (see credits.md).
+*Transitive* `local.sources` overrides across repositories are also supported.