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