Build change follow-ups (#1420)

Follow up of #1415

---------

Co-authored-by: Hofer-Julian <30049909+Hofer-Julian@users.noreply.github.com>

.gitignore

@@ -11,7 +11,7 @@ docs/site/
 
 /generated_testmodels
 build/ribasim/
-build/cli_wrapper/target
+build/cli/target
 
 JuliaSysimage.dll
 LocalPreferences.toml

.teamcity/Ribasim/project-config.xml

@@ -25,9 +25,9 @@
     <extension id="PROJECT_EXT_107" type="IssueTracker">
       <parameters>
         <param name="authType" value="anonymous" />
-        <param name="name" value="Ribasim Github Issues" />
+        <param name="name" value="Ribasim GitHub Issues" />
         <param name="pattern" value="#(\d+)" />
-        <param name="repository" value="https://github.com/Deltares/Ribasim.jl" />
+        <param name="repository" value="https://github.com/Deltares/Ribasim" />
         <param name="secure:accessToken" value="" />
         <param name="secure:password" value="" />
         <param name="type" value="GithubIssues" />

build/README.md

@@ -1,18 +1,6 @@
 # Create Binaries
 
-Build the app with:
-
-```sh
-pixi run build-ribasim-cli
-```
-
-Build the shared library with:
-
-```sh
-pixi run build-libribasim
-```
-
-Build both with:
+Build the app and shared library with:
 
 ```sh
 pixi run build

build/build.jl

@@ -3,8 +3,6 @@ using PackageCompiler
 using TOML
 using LibGit2
 
-include("src/add_metadata.jl")
-
 """
 # Ribasim CLI
 
@@ -65,10 +63,85 @@ function main()
 
     readme = @doc(build_app)
     add_metadata(project_dir, license_file, output_dir, git_repo, readme)
-    run(Cmd(`cargo build --release`; dir = "cli_wrapper"))
+    run(Cmd(`cargo build --release`; dir = "cli"))
     ribasim = Sys.iswindows() ? "ribasim.exe" : "ribasim"
-    cp("cli_wrapper/target/release/$ribasim", "ribasim/$ribasim"; force = true)
+    cp("cli/target/release/$ribasim", "ribasim/$ribasim"; force = true)
 end
 
+"""
+Add the following metadata files to the newly created build:
+
+- Build.toml
+- Project.toml
+- Manifest.toml
+- README.md
+- LICENSE
+"""
+function add_metadata(project_dir, license_file, output_dir, git_repo, readme)
+    # save some environment variables in a Build.toml file for debugging purposes
+    vars = ["BUILD_NUMBER", "BUILD_VCS_NUMBER"]
+    dict = Dict(var => ENV[var] for var in vars if haskey(ENV, var))
+    open(normpath(output_dir, "share/julia/Build.toml"), "w") do io
+        TOML.print(io, dict)
+    end
+
+    # a stripped Project.toml is already added in the same location by PackageCompiler
+    # however it is better to copy the original, since it includes the version and compat
+    cp(
+        normpath(project_dir, "Project.toml"),
+        normpath(output_dir, "share/julia/Project.toml");
+        force = true,
+    )
+    # the Manifest.toml always gives the exact version of Ribasim that was built
+    cp(
+        normpath(git_repo, "Manifest.toml"),
+        normpath(output_dir, "share/julia/Manifest.toml");
+        force = true,
+    )
+
+    # put the LICENSE in the top level directory
+    cp(license_file, normpath(output_dir, "LICENSE"); force = true)
+    open(normpath(output_dir, "README.md"), "w") do io
+        println(io, readme)
+
+        # since the exact Ribasim version may be hard to find in the Manifest.toml file
+        # we can also extract that information, and add it to the README.md
+        manifest = TOML.parsefile(normpath(git_repo, "Manifest.toml"))
+        if !haskey(manifest, "manifest_format")
+            error("Manifest.toml is in the old format, run Pkg.upgrade_manifest()")
+        end
+        julia_version = manifest["julia_version"]
+        ribasim_entry = only(manifest["deps"]["Ribasim"])
+        version = ribasim_entry["version"]
+        repo = GitRepo(git_repo)
+        branch = LibGit2.head(repo)
+        commit = LibGit2.peel(LibGit2.GitCommit, branch)
+        short_name = LibGit2.shortname(branch)
+        short_commit = string(LibGit2.GitShortHash(LibGit2.GitHash(commit), 10))
+
+        # get the release from the current tag, like `git describe --tags`
+        # if it is a commit after a tag, it will be <tag>-g<short-commit>
+        options =
+            LibGit2.DescribeOptions(; describe_strategy = LibGit2.Consts.DESCRIBE_TAGS)
+        result = LibGit2.GitDescribeResult(repo; options)
+        tag = LibGit2.format(result)
+
+        url = "https://github.com/Deltares/Ribasim/tree"
+        version_info = """
+
+        ## Version
+
+        This build uses the Ribasim version mentioned below.
+
+        ```toml
+        release = "$tag"
+        commit = "$url/$short_commit"
+        branch = "$url/$short_name"
+        julia_version = "$julia_version"
+        core_version = "$version"
+        ```"""
+        println(io, version_info)
+    end
+end
 
 main()

docs/contribute/ci.qmd

@@ -16,9 +16,9 @@ graph LR
 
 This page contains an extensive explanation on how the Ribasim continuous integration works.
 
-# Github actions
+# GitHub Actions
 
-With [GitHub Actions](https://docs.github.com/en/actions), Github provides their own continuous integration service.
+With [GitHub Actions](https://docs.github.com/en/actions), GitHub provides their own continuous integration service.
 They include the following checks:
 
 * Julia Run Testmodels: This is to make sure all the test models can be run successfully
@@ -33,18 +33,18 @@ They include the following checks:
 
 # TeamCity
 Ribasim has another cloud-based CI service based on [TeamCity](https://www.jetbrains.com/teamcity/).
-TeamCity interacts with Github and manages the release process.
+TeamCity interacts with GitHub and manages the release process.
 
 ```{mermaid}
 graph LR
-    A[TeamCity]-->|Monitoring|B[Github]
+    A[TeamCity]-->|Monitoring|B[GitHub]
     A-->C(Release)
 ```
 
 ## Conditions of using TeamCity
 TeamCity only runs workflows with the following conditions:
 
-* When the workflow would take too long to run on Github Action
+* When the workflow would take too long to run on GitHub Action
 * When the release depends on the artifacts of the workflow.
 * When other TeamCity projects depend on artifacts of Ribasim (e.g. iMOD coupler)
 
@@ -54,17 +54,17 @@ In the release, we include the generated testmodels, Ribasim CLI on Windows and
 We have the following pipeline to generate artifects for releasing:
 
 * Generate Testmodels: produces generated_testmodels artifact which is part of the release.
-* Make GitHub Release: uses artifacts and makes the release. TeamCity constantly monitors the Github repository. When a tag starts with `v20` is added, it triggers the release process.
+* Make GitHub Release: uses artifacts and makes the release. TeamCity constantly monitors the GitHub repository. When a tag starts with `v20` is added, it triggers the release process.
 * Build Ribasim: builds library and executable of Ribasim on Linux and Windows. The artifacts are tested in `Test Ribasim Binaries` and used by iMOD Coupler.
 * Test Ribasim Binaries: tests libribasim artifact and ribasim_cli artifact on Linux and Windows
 
 ::: {.callout-note}
-Make Github Release does not publish artifacts of "Test Ribasim Binaries". It only publishes artifacts of "Build Ribasim" if the beforementioned tests pass.
+Make GitHub Release does not publish artifacts of "Test Ribasim Binaries". It only publishes artifacts of "Build Ribasim" if the beforementioned tests pass.
 :::
 
 ```{mermaid}
 graph LR
-    A[Make Github Release]-->B(Release)
+    A[Make GitHub Release]-->B(Release)
     F[Generate Testmodels]-->A
     G[Make QGIS plugin]-->A
     H[Build Ribasim]---D[Test Ribasim Binaries]

docs/contribute/core.qmd

@@ -21,10 +21,10 @@ A more detailed sequence diagram of the simulation loop is available at the [cor
 Start the Julia [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) by executing `pixi run julia` in your terminal.
 Within the REPL type `]` to enter the Pkg REPL.
 For more information on how to use `Pkg`, see the [Getting Started](https://pkgdocs.julialang.org/v1/getting-started/) page in its documentation.
-There you can add `Revise` and `TestEnv` to your global environment.
+There you can add `Revise` to your global environment.
 
 ```julia
-pkg> add Revise TestEnv
+pkg> add Revise
 ```
 
 ## Setup Revise.jl
@@ -37,7 +37,7 @@ You can let it start automatically by following these [instructions](https://tim
 There is a section on editors and IDEs for Julia on <https://julialang.org/>, scroll down to see it.
 We use and recommend Microsoft's free editor [Visual Studio Code](https://code.visualstudio.com/).
 When combined with the [Julia extension](https://www.julia-vscode.org/) it provides a powerful and interactive development experience.
-Make sure to have the correct environment when opening your IDE by running `pixi run code .`, or opening a `pixi shell` and then calling the command to open the editor of your choice.
+Make sure to have the correct environment when opening your IDE by running `open-vscode.bat`, or opening a `pixi --environment=dev shell` and then calling the command to open the editor of your choice.
 
 # Developing on Ribasim
 
@@ -48,7 +48,7 @@ It is also a good way to find out if your development environment is set up corr
 
 Before the tests can run, you need to [prepare model input](python.qmd#prepare-model-input).
 
-With the root of the repository as your working directory you can start the REPL with activated `Ribasim` environment by running the following:
+With the root of the repository as your working directory you can start the REPL with activated `root` environment by running the following:
 
 ```bash
 julia --project
@@ -66,16 +66,11 @@ Then open the Pkg REPL by typing `]` and execute:
 pkg> test Ribasim
 ```
 
-In order to debug tests, it is very useful to run them in a REPL.
-However, here, you don't have the dependencies available in the `[extras]` section of your `Project.toml`.
-[`TestEnv.jl`](https://github.com/JuliaTesting/TestEnv.jl) that we installed earlier solves that problem.
+In order to debug tests, you can run individual test items from Visual Studio Code.
+Click the green play icon in front of a test item, as show in the image below.
+The first run will be slow.
 
-When you then debug your tests inside the REPL, you can include the `[extras]` dependencies as follows:
-
-```julia
-using TestEnv,
-TestEnv.activate("Ribasim")
-```
+![](https://github.com/Deltares/Ribasim/assets/4471859/58077f71-11d0-4c45-8d95-4eba8c0a0139)
 
 ## Render documentation
 
@@ -123,3 +118,23 @@ julia> Ribasim.run("path/to/model/ribasim.toml")
 The Julia VS Code extension allows you to [execute code cells in REPL](https://www.julia-vscode.org/docs/stable/userguide/runningcode/#Running-code-in-the-Julia-REPL).
 This is a very convenient way of executing only parts of your source file.
 :::
+
+## Build Ribasim
+
+The Ribasim core can be built into an executable with a command line interface (CLI) and a shared library, libribasim.
+These products will run without a Julia installation.
+To create both these products at once, run:
+
+```
+pixi run build
+```
+
+To verify that the build was successful, you can run both these commands.
+
+```
+pixi run test-ribasim-api
+pixi run test-ribasim-cli
+```
+
+During development these steps are normally done [on TeamCity](ci.qmd#TeamCity),
+though in some cases it can be more convenient to build locally.

docs/contribute/release.qmd

@@ -57,7 +57,7 @@ The possibly long list of generated release notes can put below an "All changes"
 All changes
 </summary>
 
-# Put Github flavored markdown here
+# Put GitHub flavored markdown here
 
 </details>
 

docs/python/examples.ipynb

@@ -1683,7 +1683,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "![](image/cascade-polder.jpg)"
+    "![](https://github.com/Deltares/Ribasim/assets/4471859/6dba5af2-14fb-47a5-bdfe-69c2c41f761d)"
    ]
   },
   {