Skip to content

Commit

Permalink
Editorial changes on user guide/install.md (#460)
Browse files Browse the repository at this point in the history
* Editorial changes on user_guide/install.md

* Rewrap text

---------

Co-authored-by: Peter Shin <[email protected]>
Co-authored-by: Willem van Verseveld <[email protected]>
  • Loading branch information
3 people authored Sep 10, 2024
1 parent 2477003 commit 37cf476
Showing 1 changed file with 46 additions and 49 deletions.
95 changes: 46 additions & 49 deletions docs/src/user_guide/install.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# How to install

First download and install the [current stable release of
Julia](https://julialang.org/downloads/#current_stable_release). Please see [platform
specific instructions](https://julialang.org/downloads/platform/) for further installation
instructions and if you have trouble installing Julia.

If you are new to Julia, it may be a good idea to check out the [Getting Started section of
the Julia Manual](https://docs.julialang.org/en/v1/manual/getting-started/). Links to other
learning resources can be found at
First, download and install the [current stable release of
Julia](https://julialang.org/downloads/#current_stable_release). If you have any issues
installing Julia, please see [platform specific
instructions](https://julialang.org/downloads/platform/) for further instructions.

If you are new to Julia, it might be a good idea to check out the [Getting Started section
of the Julia Manual](https://docs.julialang.org/en/v1/manual/getting-started/). You can also
find additional learning resources at
[julialang.org/learning](https://julialang.org/learning/).


Expand All @@ -16,62 +16,62 @@ Wflow can be used in two different ways, depending on the required use of the co
- If you want to stay up-to-date with the latest version, explore and modify the model code,
and write your own Julia scripts around the wflow package, we recommend installing wflow
as a [Julia](https://julialang.org/) package.
- If you don't need extra features, but just want to run simulations, a complied executable
version is available. This consists of a single executable, `wflow_cli`, allowing you to
run the model via the command line.
- If you don't need extra features, but just want to run simulations, a compiled executable
version is available. This version includes a single executable, `wflow_cli`, which allows
you to run the model via the command line.

Below we describe how to install both versions of wflow.

## Installing as Julia package

Wflow is a [Julia](https://julialang.org/) package, that can be installed through several
different ways. Below we show how to install wflow from Julia's package repository, and
how to install the latest version from GitHub.
Wflow is a [Julia](https://julialang.org/) package that can be installed in several ways.
Below, we show how to install wflow from Julia's package repository and how to install the
latest version from GitHub.

### Install from Julia's package repository

To access Julia's package manager, press `]` in the Julia REPL. To get back to the Julia
REPL, press backspace or ^C.

!!! tip
If you have not used Julia in a while, it can be a good idea to run `up` to update your
If you haven't used Julia in a while, it's a good idea to run `up` to update your
packages.
```julia-repl
pkg> up
```

Access Julia's package manager and install wflow using:
To access Julia's package manager and install wflow, use:
```julia-repl
pkg> add Wflow
```

This can take a while, especially the first time, since compatible dependencies are also
automatically looked up and installed from the Pkg General registry.
This process can take a while, especially on the first run, as compatible dependencies are
automatically resolved and installed from the Pkg General registry.

### Install from GitHub

It is also possible to install wflow from the `master` branch as follows:
You can also install wflow from the `master` branch on the repository as follows:

```julia-repl
pkg> add Wflow#master
```

This command will track the `master` branch, and will update to the latest commit on that
branch when you run `update`, or simply `up`, in the Pkg REPL. The use of `add` will install
wflow in you home directory under `.julia/packages/Wflow`. Note that packages installed
under `packages` by `add` are supposed to never be altered in that location, for Pkg and
it's automatic dependency handling to work well.
This command tracks the `master` branch and updates to the latest commit on that branch when
you run `update`, or simply `up`, in the Pkg REPL. The `add` installs wflow in your home
directory under `.julia/packages/Wflow`. Note that packages installed under `packages` by
`add` should not be changed in the directory, as the change could disrupt Pkg's automatic
dependency handling.

If you want to make any changes to any of the files in the repository, you need to do
a development install. This can be done using:
If you want to modify any files in the repository, you need to do a development install.
This can be done using:

```julia-repl
pkg> dev Wflow
```

This will clone the git repository, put it under your home directory in `.julia/dev/Wflow`,
and add the wflow package to your project environment. Note that to receive updates, you
have to pull in the latest changes yourself using `git pull`.
This will clone the git repository, place it under your home directory in
`.julia/dev/Wflow`, and add the wflow package to your project environment. To receive
updates, you'll need to pull the latest changes manually using `git pull`.

### Check installation of wflow

Expand All @@ -81,22 +81,22 @@ Finally, go back to the Julia REPL and try to load wflow:
julia> using Wflow
```

The first time this will take longer as any package that is new or changed needs to be
pre-compiled first, to allow faster loading on subsequent uses. No error messages should
appear, indicating that you have now successfully installed wflow.
The first time you do this, it may take longer as any new or changed packages need to be
precompiled to enable faster loading on subsequent uses. No error messages should appear,
which indicates that you have successfully installed wflow.

Before ending this section, we want to recommend a few tools that can make using and
developing Julia code easier.
Before concluding this section, we recommend a few tools that can make using and developing
Julia code easier.

!!! tip
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 and open source [Visual Studio
Code](https://code.visualstudio.com/). When combined with the [Julia
Code](https://code.visualstudio.com/). Combined with the [Julia
extension](https://www.julia-vscode.org/) it provides a powerful and interactive
development experience.

!!! tip
When planning to make changes to the code of wflow, we recommend installing the `Revise.jl`
If you plan to modify the code of wflow, we recommend installing the `Revise.jl`
package. This package allows you to modify code and use the changes without restarting
Julia. Install it with `add Revise` from the Pkg REPL. Then create a file called
`.julia/config/startup.jl`, and put `using Revise` there. This will load Revise every
Expand All @@ -106,28 +106,25 @@ developing Julia code easier.

Binaries of `wflow_cli` can be downloaded from our website
[download.deltares.nl](https://download.deltares.nl/en/download/wflow/), and are currently
available for Windows. Download and install the `.msi` file. After installing you can see
two folders in the installation directory. It is only the `bin/wflow_cli` that is used. The
artifacts folder contains binary dependencies such as netCDF.
available for Windows. Download and install the `.msi` file. After installation, you will
see two folders in the installation directory. Only the `bin/wflow_cli` is used. The
`artifacts` folder contains binary dependencies such as netCDF.

```
artifacts\
bin\wflow_cli
```

Check whether the installation was performed successfully by running `wflow_cli` with no
arguments in the command line. This will give the following message:
To verify whether the installation was completed successfully, run `wflow_cli` with no
arguments in the command line. This will display the following message:

```
Usage: wflow_cli 'path/to/config.toml'
```


!!! note
The old version of wflow, based on Python and PCRaster libraries is also available to
download from our website [download.deltares.nl](https://download.deltares.nl/en/download/wflow/).
We recommend installing the Julia version, as this documentation is written to support
this version.



!!! note
The old version of wflow, which was based on Python and PCRaster libraries, is also
available for download from our website
[download.deltares.nl](https://download.deltares.nl/en/download/wflow/). We recommend
installing the Julia version, as this documentation is written to support this version.

0 comments on commit 37cf476

Please sign in to comment.