|
1 | 1 | # Building the development version of the Cardano node on Windows |
2 | 2 |
|
3 | | -This document explains how to build a __DEVELOPMENT__ version of the `cardano-node`. |
4 | | -Note that this is *not* for building a __PRODUCTION__ version of the node. |
| 3 | +This document explains how to build a __DEVELOPMENT__ version of the `cardano-node`. Note that this is *not* for building a __PRODUCTION__ version of the node. |
5 | 4 |
|
6 | | -To start building on `Windows`, you will need to install and configure specific tools outlined below. We recommend using [chocolatey](https://chocolatey.org), which provides the `choco` command to install these tools. |
| 5 | +See [install.md](./install.md) for a more thorough explanation of the dependencies and packages that have to be installed to run a node. Although the installation instructions in that document are aimed at building on Linux, large parts of the text are interesting to Windows users as well. |
7 | 6 |
|
8 | | -You can run all the instructions that invoke `choco` in PowerShell with root privileges. We recommend installing and using `git-bash` for development purposes, which is `git` when installed with `choco install git`. |
| 7 | +## Install the Haskell environment |
9 | 8 |
|
10 | | -## Install GHC |
| 9 | +The recommended way to install the Haskell tools is via [GHCup](https://www.haskell.org/ghcup/). Check [this page](https://www.haskell.org/ghcup/install/) for further explanation on the installation process. |
11 | 10 |
|
12 | | -The recommended way is to run the following command in PowerShell: |
| 11 | +Once GHCup is installed, open a new terminal (to get an updated environment) and run: |
13 | 12 |
|
14 | | -```PowerShell |
15 | | -choco install --version 8.10.7 ghc |
| 13 | +```bash |
| 14 | +ghcup install ghc 8.10.7 |
| 15 | +ghcup install cabal 3.6.2.0 |
| 16 | +ghcup set ghc 8.10.7 |
| 17 | +ghcup set cabal 3.6.2.0 |
16 | 18 | ``` |
17 | 19 |
|
18 | | -## Install pkg-config |
| 20 | +## Install MSYS2 and basic dependencies |
19 | 21 |
|
20 | | -```PowerShell |
21 | | -choco install pkgconfiglite |
| 22 | +### GHCUP and MSYS2 |
| 23 | + |
| 24 | +Note that the GHCUP comes with its own installation for MSYS2, and it can be used to build `cardano-node`. You can start the MSYS2 shell with |
| 25 | +```cmd |
| 26 | +<ghcup-path>\msys64\msys2_shell.cmd -defterm -here -no-start -mingw64 |
| 27 | +``` |
| 28 | + |
| 29 | +Make sure to enable `mingw64` subsystem. It is also possible to enable `mingw64` subsystem by |
| 30 | + |
| 31 | +```bash |
| 32 | +source shell mingw64 |
| 33 | +``` |
| 34 | + |
| 35 | + |
| 36 | +The MSYS2 shell is bundled with `pacman` package manager. `GHC` is bundled with `gcc` for `mingw`. Configure your environment to use this tool-chain. |
| 37 | + |
| 38 | +```bash |
| 39 | +pacman -Syu |
| 40 | +pacman -S --needed base-devel automake git |
| 41 | +export PATH=$PATH:/mingw64/bin:<ghcup-path>/bin:<ghcup-path>/ghc/<ghc-version>/mingw/bin |
| 42 | +``` |
| 43 | + |
| 44 | +Alternatively, you can update the `mingw64` tool-chain, that adds number of packages including latest `gcc`. This may give rise to `crt` linker error. Please read the [section - global cabal configuration](#global-cabal-configuration) to mitigate the error. |
| 45 | + |
| 46 | +```bash |
| 47 | +pacman -S mingw-w64-x86_64-toolchain |
22 | 48 | ``` |
23 | 49 |
|
24 | | -## Install vcpkg |
| 50 | +### Installing MSYS independently |
25 | 51 |
|
26 | | -You will first need to install `vcpkg` to proceed with `libsodium` library installation (which is the next step). |
| 52 | +Go to [the MSYS2 website](https://www.msys2.org/) and follow its instructions to install MSYS2. It will also install `pacman`. Then, update and upgrade all `pacman` packages and install basic dependencies: |
| 53 | + |
| 54 | +``` |
| 55 | +pacman -Syu |
| 56 | +pacman -S --needed base-devel mingw-w64-x86_64-toolchain git |
| 57 | +``` |
27 | 58 |
|
28 | | -For this, use `git`(which you can also install using `choco`) and follow [these |
29 | | -instructions](https://github.com/microsoft/vcpkg#quick-start-windows). |
| 59 | +## Installing and configuring third party libraries |
| 60 | +You can use `vcpkg`, or `pacman` or both to install third party libraries. Following are the dependencies for `cardano-node`. |
| 61 | + |
| 62 | +| package | `vcpkg` | `pacman` | Remarks |
| 63 | +|-----------|-----------|----------------------------|-------------------------------------- |
| 64 | +| libsodium | libsodium | mingw-w64-x86_64-lmdb | |
| 65 | +| lmdb | lmdb | mingw-w64-x86_64-libsodium | |
| 66 | +| secp256k1 | secp256k1 | __not available__ | `vcpkg` package is not complete. |
| 67 | +| openssl | openssl | mingw-w64-x86_64-openssl | |
| 68 | +|-----------|-----------|----------------------------|-------------------------------------- |
| 69 | + |
| 70 | +### Using __vcpkg__ |
| 71 | +- Install `vcpkg` for MSYS2 with instruction given [here](https://vcpkg.io/en/docs/users/mingw.html) |
| 72 | +- Set following variables for installing libraries |
| 73 | + ```bash |
| 74 | + export VCPKG_DEFAULT_TRIPLET=x64-mingw-static |
| 75 | + export VCPKG_DEFAULT_HOST_TRIPLET=x64-mingw-dynamic |
| 76 | + ``` |
| 77 | +- You can also use `x64-mingw-dynamic` for `VCPKG_DEFAULT_TRIPLET`, if you'd like to use shared libraries |
| 78 | +- Install libraries |
| 79 | + ```bash |
| 80 | + vcpkg install libsodium |
| 81 | + vcpkg install openssl |
| 82 | + vcpkg install lmdb |
| 83 | + ``` |
| 84 | +- __cardano-crypto-class__ uses several features of `secp256k1` that are not compiled into `vcpkg` package. Hence it needs to be compiled separately. |
| 85 | +- `vcpkg` generates `pkg-config` when it can. It generates configuration for `openssl`. To avoid mixing configurations with existing system, you can use following to install packages |
| 86 | + ```bash |
| 87 | + PATH="${PATH/:\/usr\/bin:\/bin:/:}:/ming64/bin" ./vcpkg.exe install <pkg-name> |
| 88 | + ``` |
| 89 | + + Note that packages will be generated at `<vc-pkg>/installed/${VCPKG_DEFAULT_TRIPLET}/lib/pkgconfig`. |
| 90 | + |
| 91 | +### Using __MSYS2 pacman__ |
| 92 | + |
| 93 | +You can search for packages [here](https://packages.msys2.org/) |
| 94 | + |
| 95 | +- Install dependencies as below |
| 96 | + ```bash |
| 97 | + pacman -S mingw-w64-x86_64-libsodium |
| 98 | + pacman -S mingw-w64-x86_64-lmdb |
| 99 | + pacman -S mingw-w64-x86_64-openssl |
| 100 | + ``` |
| 101 | + |
| 102 | +### Install Secp256k1 |
| 103 | + |
| 104 | +You can use `secp256k1` either by downloading from hydra. Or by downloading from [github](https://github.com/bitcoin-core/secp256k1) |
30 | 105 |
|
31 | | -You can now install `libsodium` with the following command: |
32 | | -```bash |
33 | | -./vcpkg install --triplet x64-windows libsodium |
| 106 | +``` |
| 107 | +pacman -S unzip |
| 108 | +curl https://hydra.iohk.io/job/Cardano/haskell-nix/windows-secp256k1/latest/download/1 -o secp256k1.zip |
| 109 | +mkdir secp256k1 |
| 110 | +cd secp256k1/ |
| 111 | +unzip ../secp256k1.zip |
| 112 | +cp -r * /mingw64 |
34 | 113 | ``` |
35 | 114 |
|
36 | | -## Create libsodium.pc file |
| 115 | +If `unzip` complains that `../secp256k1.zip` is not a zip file, unzip the |
| 116 | +file manually in the explorer by choosing the option to unzip from the |
| 117 | +right-click menu. |
37 | 118 |
|
38 | | -To find system dependencies like `libsodium`, `cabal` uses `pkg-config`. On Windows, you will need to create the `libsodium.pc` description file in a correct |
39 | | -directory. |
| 119 | +### Managing package configuration |
| 120 | +Make sure that package configurations are correectly installed. If you are using chocolatey or other tool, it may be possible that more than one `pkg-config` tools are installed. You are encouraged to use `pkg-config` that __MSYS2__ has to minimize the error. Also make sure that the pkg configuration are discoverable by checking that `pkg-config --list-all` lists all the installed packages. |
| 121 | + |
| 122 | +Note that the pkg-config will only look in the paths pointed to by `pkg-config --variable pc_path pkg-config`. Also check if pkg-config correctly displays library path, by checking `pkg-config --variable libdir <pkg-name>`. In case, the path is incorrectly displayed, modify the file `pkg-config --path <pkg-name>` to correct the path. |
40 | 123 |
|
41 | | -In one of the paths reported by: |
42 | | -```bash |
43 | | -pkg-config --variable pc_path pkg-config |
44 | | -``` |
45 | | -create `libsodium.pc` file, which contains: |
46 | 124 |
|
47 | | -``` |
48 | | -libdir=VCPKG_PATH/installed/x64-windows/bin |
49 | | -includedir=VCPKG_PATH/installed/x64-windows/include |
50 | 125 |
|
51 | | -Name: libsodium |
52 | | -VERSION: LIBSODIUM_VERSION |
53 | | -Description: libsodium library |
54 | | -Cflags: -I${includedir}/sodium |
55 | | -Libs: -L${libdir} -llibsodium |
| 126 | +## Global `cabal` configuration |
| 127 | + |
| 128 | +Modify the following entries to your global `cabal` config file in your |
| 129 | +`\path\to\cabal\` directory, such that they look like this: |
| 130 | + |
56 | 131 | ``` |
57 | | -> Note that you need to replace `VCPKG_PATH` with the |
58 | | -absolute path, where you use `vcpkg`, and `LIBSODIUM_VERSION` with the version |
59 | | -number of `libsodium` which was installed on your system. Please verify that |
60 | | -the paths above contain |
61 | | -`libsodium.dll` file and headers. |
| 132 | +-- extra-include-dirs: |
| 133 | +extra-lib-dirs: C:\ghcup\ghc\8.10.7\mingw\x86_64-w64-mingw32\lib |
| 134 | +extra-prog-path: C:\ghcup\bin, |
| 135 | + path\to\cabal\bin |
| 136 | +``` |
| 137 | + |
| 138 | +Depending on the installation procedure, the path to your `\path\to\cabal\` directory could be `C:\Users\<username>\AppData\Roaming\cabal`). |
62 | 139 |
|
63 | | -> Also, you cannot use `prefix=` in the `libsodium.pc` file. This might be changed for |
64 | | -some other directory, `pkg-config` provides a switch to use the provided |
65 | | -`prefix`, but there is no way to instruct `cabal` to do so. |
| 140 | +> Note: The instructions in this section are a workaround for a |
| 141 | +> [GHCup bug](https://github.com/msys2/MINGW-packages/issues/10837#issuecomment-1047105402). |
66 | 142 |
|
67 | | -## `cabal` configuration |
| 143 | +## Downloading the source code for cardano-node |
68 | 144 |
|
69 | | -Go to the directory, where you cloned the `cardano-node` repository and add the command below |
70 | | -to your `cabal.project.local` file (if you don't already have it, create one): |
| 145 | +Create a working directory for your builds: |
71 | 146 |
|
| 147 | +```bash |
| 148 | +mkdir -p ~/src |
| 149 | +cd ~/src |
72 | 150 | ``` |
73 | | -max-backjump: 5000 |
74 | | -reorder-goals: True |
75 | 151 |
|
76 | | -package cardano-crypt-praos |
77 | | - flags: -external-libsodium-vrf |
| 152 | +Download the Cardano node sources: |
78 | 153 |
|
79 | | -extra-lib-dirs: "VCPKG_PATH\\installed\\x64-windows\\bin" |
80 | | -extra-include-dirs: "VCPKG_PATH\\installed\\x64-windows\\include" |
| 154 | +```bash |
| 155 | +git clone https://github.com/input-output-hk/cardano-node.git |
81 | 156 | ``` |
82 | 157 |
|
83 | | -The final step is to add `VCPKG_PATH/installed/x64-windows/bin` to the `PATH` |
84 | | -variable. Since we are using `git-bash`, you can do this with: |
| 158 | +Change the working directory to the downloaded source code folder: |
| 159 | + |
| 160 | +```bash |
| 161 | +cd cardano-node |
| 162 | +``` |
| 163 | + |
| 164 | +## Local `cabal` configuration |
| 165 | + |
| 166 | +Add the following to the `cabal.project.local` file (if you don't already have it, create one) in the source code folder: |
85 | 167 |
|
86 | 168 | ``` |
87 | | -export PATH="VCPKG_PATH/installed/x64-windows/bin:${PATH}" |
| 169 | +package lmdb |
| 170 | + extra-lib-dirs: "<lmdb-library-path> Or standard path E.g. C:\\msys64\\mingw64\\include or C:/tools/ghcup/msys64/mingw64/lib" |
| 171 | + extra-include-dirs: "<lmdb-library-path> Or standard path E.g. C:\\msys64\\mingw64\\include or C:/tools/ghcup/msys64/mingw64/include" |
| 172 | +
|
| 173 | +-- If pkg-config is available, use it. |
| 174 | +package HsOpenSSL |
| 175 | + flags: +use-pkg-config |
| 176 | +
|
| 177 | +package cardano-crypt-praos |
| 178 | + flags: -external-libsodium-vrf |
88 | 179 | ``` |
89 | | -*Remember to substitute `VCPKG_PATH` with the real path.* |
| 180 | + |
| 181 | +## Building and installing the node |
90 | 182 |
|
91 | 183 | You can now build the node with: |
92 | 184 |
|
93 | 185 | ```bash |
| 186 | +cabal update |
94 | 187 | cabal build --builddir /c/dist exe:cardano-node |
95 | 188 | ``` |
96 | | -> Note: using `--builddir /c/dist` with a succinct directory protects you |
97 | | -from exceeding the [maximal path |
98 | | -size](https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation) |
99 | | -on Windows (which is a limitation of the linker rather than `ghc` itself). |
100 | 189 |
|
101 | | -You can now verify whether the node runs: |
| 190 | +> Note: using `--builddir /c/dist` with a succinct directory protects you from exceeding the [maximal path size](https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation) on Windows (which is a limitation of the linker rather than `ghc` itself). |
| 191 | +
|
| 192 | +You can now verify whether the node runs: |
102 | 193 | ```bash |
103 | 194 | cabal run --builddir /c/dist exe:cardano-node -- run --help |
104 | 195 | ``` |
| 196 | + |
| 197 | +## Notes |
| 198 | + |
| 199 | +### Speed up compilation |
| 200 | + |
| 201 | +`reorder-goals` can affect the compilation time negatively. You can disable `reorder-goals` by setting it to `False` in `cabal.project.local`. |
0 commit comments