SpECTRE Documentation Coverage Report
 Current view: top level - __w/spectre/spectre/docs/DevGuide - QuickStartDockerVSCode.md Hit Total Coverage Commit: 3f09028930c0450a2fb61ee918b22882f5d03d2b Lines: 0 1 0.0 % Date: 2021-10-22 20:52:16 Legend: Lines: hit not hit
  Line data Source code  1 0 : \cond NEVER 2 : Distributed under the MIT License. 3 : See LICENSE.txt for details. 4 : \endcond 5 : # Code development quick-start with Docker and Visual Studio Code {#dev_guide_quick_start_docker_vscode} 6 : 7 : This page describes how to get started developing SpECTRE on Mac, Linux, or 8 : Windows using [Docker](https://docker.com) and the [Visual Studio 9 : Code](https://code.visualstudio.com) editor. This is a particularly quick way to 10 : get up and running with SpECTRE code development, though of course not the only 11 : way. If you prefer setting up your development environment differently, we 12 : suggest you read the \ref installation "Installation" page. If you would like to 13 : jump right into a working development environment, read on! 14 : 15 : ## Fork the SpECTRE repository on GitHub 16 : 17 : The SpECTRE code lives on GitHub in the 18 : [sxs-collaboration/spectre](https://github.com/sxs-collaboration/spectre) 19 : repository. Developers work on their own copy (or 20 : ["fork"](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-forks)) 21 : of the repository and contribute back to 22 : [sxs-collaboration/spectre](https://github.com/sxs-collaboration/spectre) 23 : through [pull requests](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests). 24 : Fork the repository to your own account: 25 : 26 : - [Fork sxs-collaboration/spectre on GitHub](https://github.com/sxs-collaboration/spectre/fork) 27 : 28 : ## Clone the SpECTRE repository to your computer 29 : 30 : To work on SpECTRE code you will need a local copy (or "clone") of the 31 : repository on your computer. We use SSH to communicate with GitHub, so you need 32 : to set up your SSH keys first. Follow GitHub's instructions to generate an SSH 33 : key and add it to your GitHub account: 34 : 35 : - [Generating an SSH key and adding to to GitHub](https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) 36 : 37 : Now you can download the repository via SSH. Navigate to **your fork** of the 38 : SpECTRE repository (i.e. the repository at the URL 39 : https://github.com/YOURNAME/spectre). Follow GitHub's instructions to clone the 40 : repository to your computer, selecting the SSH option: 41 : 42 : - [Cloning a repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) 43 : 44 : ## Enable the development environment in the repository 45 : 46 : The development environment is included in the repository, but not enabled by 47 : default. To enable it, copy or symlink the directory 48 : support/DevEnvironments/.devcontainer to the repository root. This is easiest 49 : done with the command line. Navigate into the repository that you just cloned to 50 : your computer: 51 : 52 :  53 : cd spectre 54 :  55 : 56 : Now symlink the development environment: 57 : 58 :  59 : ln -s support/DevEnvironments/.devcontainer .devcontainer 60 :  61 : 62 : ## Install Docker 63 : 64 : On your computer you will need Docker to run the containerized development 65 : environment. Install and start Docker: 66 : 67 : - [Get Docker](https://docs.docker.com/get-docker/) 68 : 69 : If you're new to Docker, you can read through Docker's [Getting 70 : started](https://docs.docker.com/get-started/) documentation to learn about 71 : their basic concepts. We will use Docker to download and jump into a prebuilt 72 : development environment that has everything installed to compile and run 73 : SpECTRE. 74 : 75 : ## Install Visual Studio Code 76 : 77 : We will use the Visual Studio Code editor to jump into the containerized 78 : development environment, edit code, compile executables and run them. Download 79 : and install Visual Studio Code: 80 : 81 : - [Get Visual Studio Code](https://code.visualstudio.com) 82 : 83 : Microsoft maintains [extensive 84 : documentation](https://code.visualstudio.com/docs) for Visual Studio Code that 85 : you can read to get started using the editor. We recommend you take a look 86 : through the [Tips and 87 : Tricks](https://code.visualstudio.com/docs/getstarted/tips-and-tricks) to get an 88 : idea of the editor's features. 89 : 90 : ## Install the "Remote - Containers" extension 91 : 92 : Visual Studio Code's "Remote - Containers" extension lets you run the editor in 93 : a Docker container. Install the extension: 94 : 95 : - [Install the "Remote - Containers" 96 : extension](vscode:extension/ms-vscode-remote.remote-containers) 97 : 98 : ## Open the SpECTRE repository in Visual Studio Code 99 : 100 : Now open the SpECTRE repository that you have cloned to your computer in Visual 101 : Studio Code. Depending on your operating system you can select File > Open, 102 : type Cmd+O (macOS) or Ctrl+O (Linux or Windows), drag the repository folder 103 : onto the Visual Studio Code icon or any other means to open the folder in Visual 104 : Studio Code. 105 : 106 : Now is also time to learn how to use the single most important tool in Visual 107 : Studio Code, the command palette. Try it now: Hit Cmd+P (macOS) or Ctrl+P 108 : (Linux or Windows) and start typing the name of any file, for example 109 : QuickStart.md. Hit Enter to open the file. This is how you can quickly open 110 : any file in the repository. Note that the search is fuzzy, so you can type any 111 : few letters in the path to the file. In addition to opening files, you can hit 112 : Cmd+Shift+P (macOS) or Ctrl+Shift+P (Linux or Windows) and type the name of 113 : any command that Visual Studio Code supports (or parts of it), for example 114 : Preferences: Open User Settings. 115 : 116 : ## Reopen the SpECTRE repository in the development container 117 : 118 : Open the command palette by hitting Cmd+Shift+P (macOS) or Ctrl+Shift+P 119 : (Linux or Windows) and run the command Remote-Containers: Reopen in container 120 : by starting to type a few letters of this command and then hitting Enter. 121 : 122 : Visual Studio Code will download and run the container and drop you into a fully 123 : configured environment where you can proceed to compile and run SpECTRE. 124 : 125 : If you are interested to learn more about this feature works you can 126 : read through the [VS Code documentation on remote containers](https://code.visualstudio.com/docs/remote/containers) 127 : and inspect the .devcontainer/devcontainer.json file that's included in the 128 : SpECTRE repository. 129 : 130 : ## Configure, compile and run SpECTRE 131 : 132 : With Visual Studio Code running in the development container you can now 133 : configure, compile and run SpECTRE with no additional setup. Hit Cmd+Shift+P 134 : (macOS) or Ctrl+Shift+P (Linux or Windows) to open the command palette and run 135 : the command CMake: Configure. It will set up a build directory. You can open 136 : Visual Studio Code's [integrated 137 : terminal](https://code.visualstudio.com/docs/editor/integrated-terminal) with 138 : the keyboard shortcut Ctrl+  and navigate to the newly created build 139 : directory to inspect it: 140 : 141 :  142 : cd build-Default-Debug 143 :  144 : 145 : For compiling and running SpECTRE you can either use Visual Studio Code's CMake 146 : integration by looking up further commands in the command palette, or use the 147 : terminal. We will be using the terminal from now on. Try compiling an 148 : executable, for example: 149 : 150 :  151 : make -j4 ExportCoordinates3D 152 :  153 : 154 : Once the executable has compiled successfully you can try running it: 155 : 156 :  157 : ./bin/ExportCoordinates3D \ 158 : --input-file $SPECTRE_HOME/tests/InputFiles/ExportCoordinates/Input3D.yaml 159 :  160 : 161 : This executable produced a volume data file that we can visualize in ParaView. 162 : Generate an XMF file from the volume data file that ParaView understands: 163 : 164 :  165 :$SPECTRE_HOME/src/Visualization/Python/GenerateXdmf.py \ 166 : --file-prefix ExportCoordinates3DVolume --subfile-name element_data \ 167 : --output ExportCoordinates3DVolume 168 :  169 : 170 : Since the build directory is shared with the host file system you can now open 171 : ParaView on your computer and load the generated XMF file as described in the 172 : \ref tutorial_visualization "visualization tutorial". 173 : 174 : ## Edit and contribute code to SpECTRE with VS Code 175 : 176 : You are now ready to code! The other \ref dev_guide "dev guides" will teach you 177 : how to write SpECTRE code. Return to the [Visual Studio Code 178 : documentation](https://code.visualstudio.com/docs) to learn more about editing 179 : code with Visual Studio Code. 180 : 181 : In particular, the Visual Studio Code documentation can teach you how to use Git 182 : to commit your code changes to your repository: 183 : 184 : - [Git support in Visual Studio Code](https://code.visualstudio.com/docs/editor/versioncontrol#_git-support) 185 : 186 : SpECTRE code development follows a pull-request model. You can learn more about 187 : this process in our contributing guide: 188 : 189 : - [Contributing to SpECTRE through pull requests](https://spectre-code.org/contributing_to_spectre.html#pull-requests) 190 : 191 : Visual Studio Code can also help you create and review pull requests: 192 : 193 : - [Working with pull requests in VS Code](https://code.visualstudio.com/docs/editor/github#_pull-requests) 194 : 195 : ## Interactively debug a SpECTRE test with VS Code 196 : 197 : To track down an issue with your code it can be very useful to interactively 198 : debug it. First, make sure you have written a test case where the issue occurs. 199 : If you have not written a test yet, this is a great time to do it. Refer to the 200 : \ref writing_unit_tests "Writing Unit Tests" dev guide to learn how to write 201 : tests. 202 : 203 : Now configure the RunSingleTest executable to run your particular test so you 204 : don't have to repeatedly compile the extensive RunTests executable. Also refer 205 : to the \ref writing_unit_tests "Writing Unit Tests" dev guide for this. 206 : 207 : To launch the interactive debugger, hit Cmd+Shift+P (macOS) or Ctrl+Shift+P 208 : (Linux or Windows) to open the command palette, run the command CMake: Set 209 : Debug Target and select RunSingleTest. Then run the command CMake: Debug. 210 : The test executable will compile, run and stop on any breakpoints. Follow the 211 : Visual Studio Code documentation to learn how to set breakpoints in your code 212 : and inspect the state of your variables: 213 : 214 : - [Debug actions in VS Code](https://code.visualstudio.com/docs/editor/debugging#_debug-actions) 215 : 216 : ## Real-time collaboration with Live Share 217 : 218 : You can use the [Live 219 : Share](https://docs.microsoft.com/en-us/visualstudio/liveshare/) extension to 220 : work together with others and edit code simultaneously. Live Share can be very 221 : useful to debug code together. Follow these instructions to share a link to your 222 : current Visual Studio Code workspace: 223 : 224 : - [Live Share Quickstart: Share your first project](https://docs.microsoft.com/en-us/visualstudio/liveshare/quickstart/share) 225 : 226 : 227 : ## Tips and tricks 228 : 229 : - The [**GitLens extension**](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) 230 : is very useful to browse your repository. Select the "Source Control" icon and 231 : explore the various panels. 232 : 233 : - When you build the **documentation** (e.g. with make doc), you can open it 234 : in a web server within VS Code: 235 : 236 :  237 : python3 -m http.server -d docs/html 238 :  239 : 240 : The web server launches on port 8000 by default, which is being forwarded 241 : outside the container, so you can just open http://127.0.0.1:8000 in your 242 : browser to view the documentation. 243 : 244 : - Instead of working in the Docker container, you can use the [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) 245 : extension to **work on a remote machine** such as your local supercomputing 246 : cluster. Ask the cluster administrators or users for suggestions concerning 247 : installing and running SpECTRE on the particular supercomputer. 248 : 249 : - You can work with **Jupyter notebooks in Visual Studio Code**. First, install 250 : Jupyter and all other Python packages you want to work with in the container: 251 : 252 :  253 : pip3 install jupyter matplotlib 254 :  255 : 256 : Any .ipynb notebook files you create or open will be displayed in VS Code's 257 : notebook editor. This is very useful for quickly plotting data from SpECTRE 258 : runs or using SpECTRE's Python bindings. Refer to the [VS Code documentation 259 : on Jupyter support](https://code.visualstudio.com/docs/python/jupyter-support) 260 : for more information. 261 : 262 : - Docker can quickly use up a lot of disk space. From time to time you 263 : can "prune" unneeded images and containers to reclaim disk space: 264 : 265 : - [Prune unused Docker objects](https://docs.docker.com/config/pruning/) 266 : 267 : When pruning containers, make sure no data is deleted that you care about! `

 Generated by: LCOV version 1.14