Skip to content
Snippets Groups Projects
Select Git revision
  • 5d230712cc0489242e1771463b9840060d3557c9
  • main default protected
2 results

devcontainer.md

Blame
    • devcontainer.md 9.95 KiB

    Dev Container

    Table of contents

    Setup the dev container

    Visual Studio Code

    Visual Studio Code (short: VS Code) is a popular code editor. It is required if you want to use the dev container.

    You can download it from the official website for all platforms: https://code.visualstudio.com/Download

    If you are on a Linux distribution that isn't listed in the link above use the following guide: https://code.visualstudio.com/docs/setup/linux

    Dev Container Extension

    The development environment for this course is packaged inside a Dev Container. This is essentially a Docker container with all the required C++ tools installed and a pre-configured VS Code environment.

    To use the container the VS Code Dev Container extension is required:

    1. Open Visual Studio Code.
    2. On the right side there is an icon consisting of four squares, click on it. Or use the keyboard shortcut ⌃ Ctrl+⇧ Shift+X (MacOS: ⇧ Shift+⌘ Command+X) to open the Extension tab.
    3. Inside the search bar type in ms-vscode-remote.remote-containers.
    4. Install the extension.

    Use the dev container

    Open your assignment in the container

    IMPORTANT: Make sure that you have set up the SSH authentication agent. You can find all the necessary information in our guide Starting the the SSH Agent.

    First you have to clone your assignment repository from TU Graz GitLab. You can choose whether you want to clone with Git or with VS Code, choose the one you prefer.

    1. Open your OOP1 assignment repository in TU Graz GitLab
    2. Click on the highlighted "Code" button in the upper right corner and copy the link under Clone with SSH.
      • It is important that you copy the SSH link and not the HTTPS link.
    3. Clone using Git:
      1. Go to the location where you want to save the assignment and then enter the command git clone <url> in the terminal. Replace <url> with the previously copied SSH link of your assignment repository.
      2. Open Visual Studio Code and click File -> Open Folder to open your cloned OOP1 assignment repository.
      3. Continue with step 5
    4. Clone using VS Code:
      1. Inside Visual Studio Code open the command pallette (Windows/Linux: ⌃ Ctrl+⇧ Shift+P, MacOS: ⌘ Command+⇧ Shift+P) and enter the command Git: Clone.
      2. Enter the previously copied SSH link of your assignment repository, select a storage location for the repository and confirm to open the project.
      3. Continue with step 5
    5. The project should be recognize immediately and ask you on the bottom right if you want to reopen it in the container.
      • If it doesn't, open the command pallette (Windows/Linux: ⌃ Ctrl+⇧ Shift+P, MacOS: ⌘ Command+⇧ Shift+P) and enter the command Dev Containers: Reopen in Container.
      • If you get an error while opening the container make sure you have an .ssh folder in your user profile directory. (Follow our SSH guide)

    If you are unable to start the container on Windows, try to execute the following command in a PowerShell terminal: [Environment]::SetEnvironmentVariable("HOME", "", "User") Then try to reopen your project the container again.

    Please note that launching the container for the first time may take several minutes, depending on your Internet speed, as around 1 GB has to be downloaded.

    You are now inside the pre-configured development environment and can start coding.

    Please note that the OOP1 framework and the test runner are downloaded automatically when the dev container is started for the first time. Even if the repository is already opened, it may still take some time until everything is set up. You can check the status in the terminal.

    Usually VS Code will ask you to rebuild the container after an update. You should always do this to use our latest dev container.

    Commit and push changes

    To be able to commit your code, you need to set your Git username and email, if you have not already done so. Simply enter the following commands in the VS Code terminal and adjust your credentials. If no terminal is shown, you can toggle it by selecting View > Terminal from the menu bar, or by pressing the keyboard shortcut ⌃ Ctrl+⇧ Shift+` (MacOS: ⌃ Control+⇧ Shift+`).

    # Use "--global" instead of "--local" if you use Git exclusively at TU Graz.
git config --local user.name "Max Muster"
git config --local user.email "max.muster@student.tugraz.at"

    For further information on how to commit your code changes and push them to the TU Graz GitLab instance, refer to the GitLab docs: https://docs.gitlab.com/ee/topics/git/commit.html

    To learn how to do these actions with vscode, check out the vscode docs: https://code.visualstudio.com/docs/sourcecontrol/overview

    Code Formatting

    You can format your code automatically by creating a custom .clang-format configuration in the root of the C++ project. The configuration will be recognized by the container and your .cpp/.hpp files will be formatted automatically on each save or by using ⇧ Shift+Alt+F (MacOS: ⇧ Shift+⌥ Option+F). You can also use the command pallette (Windows/Linux: ⌃ Ctrl+⇧ Shift+P, MacOS: ⌘ Command+⇧ Shift+P) and enter the command Format Document.

    For more information on how to create a .clang-format configuration, check out our clang-format guide: https://gitlab.tugraz.at/oop1_ws/ws2024/specification/-/tree/main/coding/clang-format.md

    File and function headers

    The container can generate file and function headers automatically. Simply type /// at the beginning of the file or above a function/method and press ⏎ Enter.

    This will automatically insert a suitable OOP1 file or function header. You now only have to adjust the description as needed.

    Building and debugging

    This section is explained in more detail in your assignment readme.

    The dev container is already pre-configured for building and debugging the OOP1 assignment. So you only have to press the F5 key to debug.

    You can read more about how to debug in the VS Code docs: https://code.visualstudio.com/docs/editor/debugging

    To build the project without debugging, execute the task Build OOP1 Project. To do this, open the "Quick Open" using the keyboard shortcut ⌃ Ctrl+P (MacOS: ⌘ Command+P) and enter task build. You can then find the compiled binaries in the build directory.

    Setting environment variables

    You may want to set environment variables when testing your program. In particular, the RAND_SEED variable is useful as it sets the seed for random functions in the assignment. This allows you to make your program deterministic, which is useful when debugging.

    To set a new environment variable, edit the .env file inside the .devcontainer folder.

    For example, if you want to set the RAND_SEED variable to 1234 you can add following content to the .devcontainer/.env file:

    RAND_SEED=1234

    Now all random functions should return the same "random" value every time you debug your program.

    Connecting to Imhotep GUI

    By default, the dev container forwards the port 50500 of your imhotep server to the host system so that the imhotep GUI can access your server. In most cases, the correct port number will be forwarded and the connection should work without any additional configuration.

    However, if the standard port (50500) is already in use by another process, the dev container will forward the imhotep server to a different port. In such cases, you will need to identify the correct port to establish a connection between server and GUI:

    1. Make sure that your imhotep server is started and running in the dev container.
    2. Open the "Ports View" by using the command pallette (Windows/Linux: ⌃ Ctrl+⇧ Shift+P, MacOS: ⌘ Command+⇧ Shift+P) and enter the command Ports: Focus on Ports View.
    3. In the ports view, look for an entry under the "Running Process" column that contains a path to your imhotep_server program. This indicates that your imhotep server is running and that the port is being forwarded.
    4. Within the same entry, you will find an address such as localhost:62621 in the "Forwarded Address" column. The number after the colon (e.g. 62621) is the correct port that you should use.

    After opening the imhotep GUI, simply click on the port number "50500" and change it to the correct port.

    Note: The forwarded port may change over time depending on your system. If this happens, you may need to repeat the above steps to find the new port in order to establish a connection.