updating docs for latest DACE_jll

a-ev · Apr 18, 2024 · b0c9e84 · b0c9e84
1 parent a634d12
commit b0c9e84
Show file tree

Hide file tree

Showing 7 changed files with 71 additions and 37 deletions.
diff --git a/README.md b/README.md
@@ -12,12 +12,11 @@ Install dependencies:
 
 ```
 $ julia --project
-(DACE) pkg> add https://github.com/chrisdjscott/DACE_jll.jl.git
 (DACE) pkg> add https://github.com/a-ev/DACE.jl.git
 ```
 
-Note: the second `add` command above may not be needed if you are
-running from this directory.
+Note: the `add` command above may not be needed if you are
+running from the directory containing this file.
 
 Run an example:
 
@@ -44,4 +43,13 @@ y(1.0)   = 0.8414709848078965
 sin(1.0) = 0.8414709848078965
 ```
 
+## Running the tests
+
 More examples of how to use *DACE.jl* can be found in the tests, for example [validation_2.jl](test/validation_2.jl).
+
+You can run the validation tests with (using `]` to enter pkg mode from the Julia REPL):
+
+```
+julia --project
+(DACE) pkg> test
+```
diff --git a/docs/src/developing.md b/docs/src/developing.md
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -12,7 +12,6 @@ DACE.jl can be installed using the Julia package manager. From the Julia REPL,
 type `]` to enter the Pkg REPL mode and run
 
 ```
-pkg> add https://github.com/chrisdjscott/DACE_jll.jl.git
 pkg> add https://github.com/a-ev/DACE.jl.git
 ```
 
@@ -24,15 +23,13 @@ running from main directory of the repository.
 - The Julia interface is built using [CxxWrap.jl](https://github.com/JuliaInterop/CxxWrap.jl)
 - The C++ source for the interface is currently in [this fork](https://github.com/a-ev/dace/tree/julia-interface/interfaces/julia)
   of the DACE library
-- The C++ code gets built and released to the DACE\_jll package
-  - DACE\_jll is located [here](https://github.com/chrisdjscott/DACE_jll.jl)
-  - the build recipe is currently [here](https://github.com/chrisdjscott/Yggdrasil/tree/beacbce0777417d58d748729e5bc1ab73604aa93/D/DACE)
+- The C++ code gets built by [BinaryBuilder](https://docs.binarybuilder.org/stable/) and released into the Julia registry
+  - the build recipe is located [here](https://github.com/JuliaPackaging/Yggdrasil/tree/master/D/DACE)
 - The Julia component of the interface is currently [here](https://github.com/a-ev/DACE.jl)
 
 The above may change, in particular we hope to:
 
 - merge the forked DACE library back to [upstream](https://github.com/dacelib/dace), if possible
-- release the DACE\_jll package with [Yggdrasil](https://github.com/JuliaPackaging/Yggdrasil)
 - move the DACE.jl package under the [dacelib](https://github.com/dacelib) organisation on GitHub, if possible
 
 ## Differences compared to the C++ interface

diff --git a/docs/src/tutorials/making-a-new-release-of-dace_jll.md b/docs/src/tutorials/making-a-new-release-of-dace_jll.md
@@ -0,0 +1,57 @@
+# Making a new release of DACE\_jll
+
+The *DACE\_jll* Julia package contains the prebuilt DACE library (prebuilt for all combinations of platforms, Julia versions, etc. that Julia is supported on).
+[BinaryBuilder.jl](https://docs.binarybuilder.org/stable/) is used to build the libraries and publish them to the Julia registry.
+
+The recipe for building the DACE library can be found on [Yggdrasil](https://github.com/JuliaPackaging/Yggdrasil) in the *D/DACE* directory.
+
+To make a new release of the DACE\_jll package you can follow these steps:
+
+1. Make your changes in the [dace](https://github.com/a-ev/dace/tree/julia-interface) repo and test them (see [setting up your development environment](setting-up-your-development-environment.md) for help getting started with this step)
+2. Commit your changes into the [dace](https://github.com/a-ev/dace/tree/julia-interface) repo and make a note of the unique commit hash that identifies the commit you want to release (this can be found using `git log` or via the commits view in the GitHub interface)
+3. On GitHub, make a fork of the [Yggdrasil](https://github.com/JuliaPackaging/Yggdrasil) repository, clone that locally and create a branch for your changes
+   ```
+   # fork in the github web interface, then...
+
+   # clone the repo (replace with the correct URL for your fork)
+   git clone [email protected]:<namespace>/Yggdrasil.git
+
+   # change directory into the repo
+   cd Yggdrasil
+
+   # switch to a new branch
+   git checkout -b update-dace
+
+   # switch to the D/DACE directory
+   cd D/DACE
+   ```
+4. Edit the *build_tarballs.jl* file:
+   - bump the version of the release on or around line 11:
+     ```
+     version = v"0.1.0"
+     ```
+
+     !!! note
+         It is highly recommended to follow [semantic versioning](https://semver.org/)
+
+   - change the commit hash (on or around line 15) that the new version will be based of to the hash of the commit you identified in step 2
+     ```
+     GitSource("https://github.com/a-ev/dace.git", "9fe534f9b27c147a171bce1ad7dc8b4706a9457e"),
+     ```
+     where *9fe534f9b27c147a171bce1ad7dc8b4706a9457e* is the commit hash
+5. Check the version of *libcxxwrap_julia_jll* which is linked to the version of *CxxWrap.jl*. When bumping the version of the CxxWrap dependency in the *DACE.jl* package you may also need to bump the version of *libcxxwrap_julia_jll* on or around line 55:
+   ```
+   Dependency("libcxxwrap_julia_jll"; compat = "~0.12.2"),
+   ```
+   
+   !!! important
+       Make sure the version of *libcxxwrap_julia_jll* is compatible with the version of *CxxWrap,jl* in your *Project.toml* for *DACE.jl*
+
+6. Commit and push your changes into your fork of Yggdrasil:
+   ```
+   git add build_tarballs.jl
+   git commit -m "[DACE] bump version"
+   git push
+   ```
+   You may need to set the upstream of your repo for `git push` to work. The above commands are just examples and may need tweaking.
+7. Create a pull request back to the main Yggdrasil repo. The builds will run automatically and you can view their status in the pull request. If they all succeed someone will merge them automatically (you don't need to do anything else)
diff --git a/docs/src/tutorials/setting-up-your-development-environment.md b/docs/src/tutorials/setting-up-your-development-environment.md
@@ -43,7 +43,7 @@ cd DACE.jl
 Run `julia --project` to enter the Julia REPL and enter `]` to enter the Pkg REPL mode, then
 
 ```julia
-(DACE) pkg> add https://github.com/chrisdjscott/DACE_jll.jl.git
+(DACE) pkg> add DACE_jll
 (DACE) pkg> develop DACE_jll
 ```
 

diff --git a/examples/polynomial_inversion.jl b/examples/polynomial_inversion.jl
@@ -14,7 +14,6 @@
 
 # ```julia
 # using Pkg
-# Pkg.add("https://github.com/chrisdjscott/DACE_jll.jl.git")
 # Pkg.add("https://github.com/a-ev/DACE.jl.git")
 # ```
 

diff --git a/examples/sine.jl b/examples/sine.jl
@@ -15,7 +15,6 @@
 
 # ```julia
 # using Pkg
-# Pkg.add("https://github.com/chrisdjscott/DACE_jll.jl.git")
 # Pkg.add("https://github.com/a-ev/DACE.jl.git")
 # ```