dev-env.md
1 # Set up local dev environment 2 3 ## Script version 4 5 This instruction is available in a script version. If you prefer it, you can run: 6 7 ``` 8 git clone -o upstream https://github.com/fedimint/fedimint && cd fedimint && ./scripts/dev/bootstrap.sh 9 ``` 10 11 and follow the instructions instead of reading this document. 12 13 ## Clone repository 14 15 Clone the fedimint git repository locally and cd into it: 16 17 ``` 18 git clone git@github.com:fedimint/fedimint.git 19 cd fedimint 20 ``` 21 22 ## Set up Nix 23 24 Fedimint uses [Nix](https://nixos.org/explore.html) for building, CI, and managing dev environment. 25 Note: only `Nix` (the language & package manager) and not the NixOS (the Linux distribution) is needed. 26 Nix can be installed on any Linux distribution and macOS. 27 28 While it is technically possible to not use Nix, it is highly recommended as 29 it ensures consistent and reproducible environment for all developers. 30 31 ### Install Nix 32 33 You have 2 options to install nix: 34 35 * **RECOMMENDED:** The [Determinate Nix Installer](https://github.com/DeterminateSystems/nix-installer) 36 * [The official installer](https://nixos.org/download.html) 37 38 Example: 39 40 ``` 41 > nix --version 42 nix (Nix) 2.9.1 43 ``` 44 45 The exact version might be different. 46 47 ### Enable nix flakes 48 49 If you installed Nix using the "determinate installer" you can skip this step. If you used the "official installer", edit either `~/.config/nix/nix.conf` or `/etc/nix/nix.conf` and add: 50 51 ``` 52 experimental-features = nix-command flakes 53 ``` 54 55 If the Nix installation is in multi-user mode, don’t forget to restart the nix-daemon. 56 57 ## Use Nix Shell 58 59 If your Nix is set up properly `nix develop` started inside the project dir should just work 60 (though it might take a while to download all the necessary files and build all the internal 61 tooling). In the meantime you can read other documentation. 62 63 **Using `nix develop` is strongly recommended**. It takes care of setting up 64 all the required developer automation, checks and ensures that all the developers and CI are 65 in sync: working with same set of tools (exact versions). 66 67 You can still use your favorite IDE, Unix shell, and other personal utilities, but they MUST NOT 68 be expected to be a requirements for other developers. In other words: if it's not automated 69 and set up in `nix develop` shell, it doesn't exist from the team's perspective. 70 71 To use a different shell for `nix develop`, try `nix develop -c zsh`. You can alias it if 72 don't want to remember about it. That's the recommended way to use a different shell 73 for `nix develop`. 74 75 ## Cachix binary cache 76 77 Fedimint uses a [Cachix](https://www.cachix.org/) binary cache to cache builds. 78 To benefit from this cache and avoid building everything from scratch, you must 79 ensure that your user is a [trusted user](https://nix.dev/manual/nix/stable/command-ref/conf-file.html#conf-trusted-users). 80 You can do this by modifying `/etc/nix/nix.conf`, adding the following line. 81 82 ``` 83 trusted-users = the_name_of_your_user 84 ``` 85 86 Alternatively, if you do not want to add your user to the list of trusted users, you can 87 run the following command, which will add <https://fedimint.cachix.org> and its public key 88 to your nix configuration. 89 90 ``` 91 nix develop .#bootstrap -c cachix use fedimint 92 ``` 93 94 ## Setting up `direnv` or `lorri` 95 96 One of the biggest QoL improvements you can do when working with flake-enabled projects 97 is setting up one of: 98 99 * https://github.com/nix-community/nix-direnv 100 * https://github.com/nix-community/lorri 101 102 The projects will set up your system's shell so that when you `cd` inside a given 103 project they will automatically set up the environment for you, without starting any 104 new shells. This way you can preserve your shell, and your settings while using 105 `nix develop`-like shell automatically. 106 107 ## Cross-compilation 108 109 Dev environment comes with support for cross-compilation. However since most developers 110 are not going use it while it requires heavy dependencies like Android NDK, it is only 111 available in a separate Nix dev shell. To start it, use: 112 113 ``` 114 nix develop .#cross 115 ``` 116 117 Inside the shell cross-compilation commands like: 118 119 ``` 120 cargo build --target wasm32-unknown-unknown --package fedimint-client 121 ``` 122 123 should work as expected. 124 125 ## Containers 126 127 The `flake.nix` exposes OCI container builds of Fedimint (search for "container"). To use them 128 try: 129 130 ``` 131 $ nix build .#container.fedimintd && docker load < ./result 132 Loaded image: fedimintd:iqviraxy2cz7apg7qamcp2mbsy7x7w8r 133 ``` 134 135 Change `.#container.fedimintd` to build a different container. 136 The `Loaded image:` lists the image name that `docker` will use. 137 138 ``` 139 $ docker images | grep iqviraxy2cz7apg7qamcp2mbsy7x7w8r 140 fedimintd iqviraxy2cz7apg7qamcp2mbsy7x7w8r fad75f704001 52 years ago 68.6MB 141 ``` 142 143 You can start the binary(-ies) inside with the usual: 144 145 ``` 146 $ docker run -it fedimintd:iqviraxy2cz7apg7qamcp2mbsy7x7w8r fedimintd --help 147 Usage: fedimintd [OPTIONS] <DATA_DIR> [PASSWORD] 148 149 Arguments: 150 <DATA_DIR> Path to folder containing federation config files 151 [PASSWORD] Password to encrypt sensitive config files [env: FM_PASSWORD=] 152 153 Options: 154 -h, --help Print help information 155 ``` 156 157 Most commands will require access to some host mounted volumes and port bindings. 158 For your convenience, here is an example: 159 160 ``` 161 $ docker run -it -v $PWD/demo:/var/fedimint -p 17240:17240 fedimintd:iqviraxy2cz7apg7qamcp2mbsy7x7w8r configgen <command> 162 ``` 163 164 `-v` will mount local directory `./demo` as `/var/fedimint` inside the container, so commands working on `/var/fedimint` 165 write the files to the host file-system (e.g. config generation). `-p` is used to bind the host's port 17240 as the 166 container's port 17240. 167 168 Note that you can also start a "fake" 1-of-1 "federation" that will allow you to test most aspects of Fedimint without 169 having to run e.g. 4 instances.