Skip to content

Latest commit

 

History

History
110 lines (73 loc) · 5.04 KB

contributing-windows.md

File metadata and controls

110 lines (73 loc) · 5.04 KB
Raw

Contributing with Windows

Introduction

In this tutorial, you will learn how to set up a development environment for Elektra using Windows Subsystem for Linux (WSL) and Visual Studio 2019.

Visual Studio 2022 (VS2022) Community is free but requires a registration after a couple of days. Download it and install the Linux development with C++ workload.

Elektra development mainly happens on GNU/Linux distributions. Therefore, it makes sense to use WSL if you have Windows 10 installed on your PC. For the beginning, it does not matter if you choose WSL 1 or WSL 2. It is possible to convert them later.

Download and Installation

We assume you use Ubuntu as WSL distribution. Install the packages required for building from VS2022:

apt install g++ gdb make ninja-build rsync zip

Then clone the libelektra git repository:

git clone [email protected]:ElektraInitiative/libelektra.git

and open it in VS2022.

Note: This command should work both in a Windows Terminal and in a WSL Shell. If you do encounter problems (especially related to line endings), please report the issue. Running the command from a WSL Shell should always work, because that uses the Linux version of git.

It will complain that IntelliSense is out of date. In addition, the Error List at the bottom will show CMake errors about missing compilers. To solve this, you have to configure a Linux CMake project.

Configure a Linux CMake project

Microsoft has even more information about this task.

In the drop-down menu that says x64-Debug (Default) click Manage Configurations.... Add WSL-GCC-Debug and save the configuration.

You can remove x64-Debug (Default).

CMake generation will automatically restart. When it has completed, you can click the drop-down Select Startup Item... (by the green Play button).

A long list of targets should appear. Choose hello (bin\hello) and click the green Play button. You should now see the output Hello world in the Linux Console Window at the bottom.

Why choose VS2022

One advantage of using VS2022 is the graphical debugger. Search for hello.c in the Solution Explorer to the right. Create a breakpoint in the main function and run the program again using the green Play button.

On the bottom-left you will see the windows Autos, Locals and Watch 1. Click on Locals to inspect the Key * k. Right-click keyNew to access functions like Peek Definition.

Disadvantages of VS2022

One problem with VS2022 is that it currently doesn't support opening project that are stored in the WSL filesystem. Accessing files on the Windows filesystem via WSL (required for compiling) is much slower. This means that compiling Elektra this way may take longer than expected.

As an alternative you may want to consider using Visual Studio Code (VSCode). VSCode doesn't have as much graphical IDE features, but it has good C/C++ support and also includes a graphical debugger. Most importantly, developing in the WSL (including within the WSL filesystem) is explicitly supported via the WSL Remote Extension.

Choosing your WSL version

It makes sense to compare WSL 1 and WSL 2 and make an informed decision for one of them. Your setup may require adaptions, such as installing an SSH server in your Linux distribution.

Good sources of information are:

Commands to change your WSL version can be found, for example, in the blog post WSL 2 is now available in Windows Insiders

Like Microsoft, we generally recommend you start with WSL2 (the default). It should provide better performance and more complete support for many use cases.

Troubleshooting

For further information, consider the official Linux with Visual Studio C++ documentation.

If you choose to work with source code residing on a Windows filesystem mounted in WSL (e.g./mnt/c/...), please enable the metadata option to prevent problems due to permissions not being persisted:

  • Create or modify /etc/wsl.conf to contain the following section and setting:
[automount]
options = "metadata"
  • Restart the WSL VM by issuing wsl --shutdown in your window console.

Building from sources residing on a mounted Windows file system may incur a significant performance penalty. Consider using your WSL home directory (e.g. ~/) as your location for the Elektra sources.