SpECTRE Documentation Coverage Report
Current view: top level - __w/spectre/spectre/docs/DevGuide - QuickStartDockerVSCode.md Hit Total Coverage
Commit: b5ffa4904430ccef0b226f73dcd25c74cb5188f6 Lines: 0 1 0.0 %
Date: 2021-07-28 22:05:18
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