Skip to content

04. Build with Windows Subsystem for Linux (WSL)

Jump to bottom
Aregtech edited this page Aug 6, 2024 · 9 revisions

Table of contents

  1. General Information
  2. How to install Linux Distribution
  3. Troubleshooting WSL Update
  4. Install Build Tools in WSL
  5. AREG SDK clone in WSL
  6. Compile AREG SDK in WSL
  7. Run applications

General Information

The Windows Subsystem for Linux (WSL) is a feature that enables developers to install and utilize Linux applications, utilities, and command-line tools directly on Windows machines running Windows 10 version 2004 and higher. With WSL, developers can seamlessly use popular Linux distributions like Ubuntu, OpenSUSE, Kali, Debian, and Arch Linux without the need to switch between operating systems or set up virtual machines.

Assuming that you have already installed WSL on your Windows machine, the following steps outline how to update WSL, install necessary packages, clone the repository, and compile the AREG SDK:

  1. Update WSL: Before proceeding with the installation of packages or applications, it is essential to ensure that your WSL installation is up to date. To accomplish this, open the Command Prompt and enter wsl --update to update WSL to the latest version.

  2. Install required packages: Depending on your specific requirements for WSL, you may need to install additional packages. For instance, to compile the AREG SDK from its source code, you will need to install the build-essential package. To install packages, utilize the package manager specific to your Linux distribution. In the case of Ubuntu, the package manager is apt-get.

  3. Clone the code: Clone the AREG SDK repository using Git. This can be achieved by executing the appropriate Git command. Once the code is cloned, navigate to the relevant directory where you will build the software.

  4. Compile the code: Utilize either make or cmake, along with the GCC or LLVM compilers, to compile the AREG SDK source code.

By following these steps, you can leverage WSL to develop and test software on your Windows machine without the need to switch to a different operating system or set up a separate virtual machine. The subsequent instructions provide guidance on how to install the Ubuntu Linux distribution, troubleshoot issues related to updates, install build packages, and perform cloning and compilation of the AREG SDK.

How to install Linux Distribution

The Windows Subsystem for Linux (WSL) allows developers to install a Linux distribution on their Windows machines. The step-by-step manual installation process for WSL is described here.

Install WSL2

To ensure you have the latest version of WSL, you can update your current WSL version to WSL2. Follow these steps:

  1. Open the Windows Command Prompt with administrative rights.
  2. Enter the following command in the command line to install WSL2: 
    wsl --install --web-download
  3. Set WSL2 as the default version by entering the following command: 
    wsl --set-default-version 2

💡 You may need to restart your PC for the changes to take effect.

Install Linux Distribution

You can choose from multiple Linux distributions to install using WSL. Check the list of available distributions here. In this manual, we will focus on installing Ubuntu. Follow these steps:

  1. Open the Windows Command Prompt with administrative rights.
  2. Enter the following command in the command line to install Ubuntu: 
    wsl --install -d ubuntu

💡 You may need to restart your PC to start and complete the installation of Ubuntu.

After the installation of Ubuntu, you will be prompted to enter a username and password. To check your Ubuntu version, open the WSL Terminal and enter the following command:

lsb_release -a

Here's an example of the Ubuntu version output:

No LSB modules are available.
Distributor ID: Ubuntu
Description: Ubuntu 22.04.1 LTS
Release: 22.04
Codename: jammy

Update Linux Distribution

Once you have installed Ubuntu Linux, it is recommended to run the update to ensure you have the latest packages. Open the WSL Terminal and enter the following command to perform the update:

sudo apt-get update | sudo apt-get upgrade -y

💡 If you encounter issues while running the update, please refer to the troubleshooting chapter for further assistance.

Troubleshooting WSL Update

If you get trouble starting WSL, for example having error message Error code: Wsl/Service/CreateInstance/0x80040326, run in command line:

wsl --update

This will fix your error to start Linux Distro.

If you encounter issues when running sudo apt-get update in WSL and it fails, follow the instructions provided in this chapter. Otherwise, you can proceed to the next chapter on installing build packages.

During the update of Ubuntu Linux, you may encounter the following error messages:

W: Failed to fetch http://archive.ubuntu.com/ubuntu/dists/jammy/InRelease Temporary failure resolving 'archive.ubuntu.com'
W: Failed to fetch http://archive.ubuntu.com/ubuntu/dists/jammy-updates/InRelease Temporary failure resolving 'archive.ubuntu.com'
W: Failed to fetch http://archive.ubuntu.com/ubuntu/dists/jammy-backports/InRelease Temporary failure resolving 'archive.ubuntu.com'
W: Failed to fetch http://security.ubuntu.com/ubuntu/dists/jammy-security/InRelease Temporary failure resolving 'security.ubuntu.com'
W: Some index files failed to download. They have been ignored, or old ones used instead.

To resolve this issue and successfully perform the update, you need to make changes to the /etc/resolv.conf file, which contains the following data when you run cat /etc/resolv.conf:

# This file was automatically generated by WSL. To stop automatic generation of this file, add the following entry to /etc/wsl.conf:
# [network]
# generateResolvConf = false
nameserver 172.23.112.1

To proceed with the troubleshooting steps, follow these instructions:

Step 1: Open the /etc/resolv.conf file for editing:

sudo vim /etc/resolv.conf

💡 If you're using vim, press the i key to enter insert mode and make the necessary changes.

Step 2: Change the nameserver value to 8.8.8.8 (Google DNS):

# This file was automatically generated by WSL. To stop automatic generation of this file, add the following entry to /etc/wsl.conf:
# [network]
# generateResolvConf = false
nameserver 8.8.8.8

Step 3: Save the changes: If you're using vim, press the Esc key, then type :wq and press Enter.

💡 Alternatively, you can execute the following command in the terminal to set the nameserver IP in the resolv.conf file:

sudo sh -c "echo nameserver 8.8.8.8 > /etc/resolv.conf"

Step 4: Perform the update: You should now be able to run the update command successfully by typing the following command in the WSL Terminal:

sudo apt-get update | sudo apt-get upgrade -y

If you continue to experience issues with running the update, you can try alternative methods to resolve the problem, which can be found here.

Install Build Tools in WSL

In order to compile the AREG SDK, you need to have C++ compilers, dependent libraries, Make, and CMake packages installed in WSL. By default, these packages are not included in the WSL installation. To install the necessary packages, follow these steps:

  1. Open the WSL Terminal.

  2. Type the following command in the terminal and press Enter:

sudo apt-get install -y g++ clang gdb make cmake libncurses-dev openjdk-17-jre

This command will install the required packages for compiling the AREG SDK in the Windows Subsystem for Linux (WSL).

💡 It's recommended to check the availability of these packages on the official webpage of your Linux distribution. For example, if you are using Ubuntu Linux, you can search for the packages by their component names on the Ubuntu Packages Search page.

Once the installation is complete, you will have all the necessary packages installed to compile the AREG SDK in WSL.

AREG SDK clone in WSL

In Windows Subsystem for Linux (WSL), developers have the option to clone the source code from a repository or utilize an existing clone within the Windows system. This flexibility allows developers to choose their preferred method of accessing the source code for their projects.

Clone AREG SDK sources in WSL

To clone the AREG SDK source code and its dependent submodules, follow these steps in your WSL Terminal:

  1. Change to your home directory by typing the following command and pressing Enter: 
    cd ~
  2. Create a directory named "projects" by typing the following command and pressing Enter: 
    mkdir projects
  3. Change to the "projects" directory by typing the following command and pressing Enter: 
    cd projects
  4. Clone the AREG SDK repository and its submodules by typing the following command and pressing Enter: 
    git clone --recurse-submodules https://github.com/aregtech/areg-sdk.git
  5. Change to the "areg-sdk" directory by typing the following command and pressing Enter: 
    cd areg-sdk

By following these steps, you will have successfully cloned the AREG SDK source code and its dependent submodules in your WSL environment. You can now proceed with compiling the AREG SDK.

Use an existing Windows source clone

If you already have a clone of the AREG SDK on your Windows system, you can easily access it within your WSL environment. The location of the existing clone can be found in the /mnt/ folder in the Linux system. Here's how you can access the existing clone in WSL:

  1. Open your WSL Terminal.

  2. Switch to the directory of your existing clone by using the Linux cd command. For example, if your AREG SDK clone is located at C:\projects\areg-sdk\ in Windows, you can access it in WSL by typing the following command and pressing Enter:

    cd /mnt/c/projects/areg-sdk/

💡 Replace /mnt/c/projects/areg-sdk/ with the actual path to your AREG SDK clone on Windows.

By following these steps, you will be able to access and work with your existing AREG SDK clone within your WSL environment. You can proceed with compiling or making changes to the code as needed.

Compile AREG SDK in WSL

To compile the AREG SDK in WSL (Windows Subsystem for Linux), you can use either cmake or make tools, depending on your preference. Here are examples of how to compile the AREG SDK using different build configurations:

Example 1: CMake build with Clang compilers and AREG extended features:

cmake -B ./build -DAREG_COMPILER_FAMILY=llvm -DAREG_BUILD_TYPE=Release -DAREG_EXTENDED:BOOL=ON
cmake --build ./build -j 8

This example uses cmake to generate the build files in the build directory. It specifies the Clang compiler as the compiler family and sets the build type to Release. Additionally, it enables the AREG extended features. The cmake --build command is used to build the project with parallel compilation (-j 8).

Example 2: CMake build with GCC compilers and AREG extended features (Debug build):

cmake -B ./build -DAREG_COMPILER_FAMILY=gnu -DAREG_BUILD_TYPE=Debug -DAREG_EXTENDED:BOOL=ON
cmake --build ./build

This example is similar to the previous one but uses the GCC compiler family and sets the build type to Debug. The AREG extended features are enabled as well. The cmake --build command is used to build the project.

Example 3: Make build with GCC compilers and AREG extended features:

make AREG_COMPILER_FAMILY=gnu AREG_EXTENDED=1 -j10

This example demonstrates how to use the make tool to build the AREG SDK. It sets the compiler family to GCC (AREG_COMPILER_FAMILY=gnu) and enables the AREG extended features (AREG_EXTENDED=1). The -j10 option specifies parallel compilation with 10 jobs.

Make sure to navigate to the AREG SDK directory (cd /path/to/areg-sdk/) in your WSL Terminal before running the compilation commands.

These examples provide an idea of how to compile the AREG SDK in WSL using different build configurations. You can modify the options and flags based on your specific requirements and the desired build settings. For more detailed instructions and information, refer to the official AREG SDK documentation in the Software build Wiki page.

Run Applications

To run applications after compiling the AREG SDK in WSL (Windows Subsystem for Linux), follow these steps:

  1. Navigate to the AREG SDK root directory in your WSL Terminal. Depending on whether you cloned the source codes in WSL or are using an existing clone in the Windows system, use one of the following commands:

    • If you cloned the source codes in WSL, run cd ~/projects/areg-sdk/.
    • If you are using an existing clone in the Windows system, run cd /mnt/c/projects/areg-sdk/.

  2. Once you are in the AREG SDK root directory, you can run the compiled applications located in the bin directory. For example, to run the 10_locservice.out application, use the following command in the WSL Terminal:

    ./product/build/llvm-clang++/linux-64-x86_64-release/bin/10_locservice.out

    This command executes the specified application, and you should see the corresponding output in the terminal.

    Example output:

    A Demo to demonstrate simple request, response, and broadcast ...
"Hello client [ TestServiceClient ]!", remain to process [ 36 ]
"Hello client [ TestServiceClient ]!", remain to process [ 35 ]

...

"Hello client [ TestServiceClient ]!", remain to process [ 1 ]
"Hello client [ TestServiceClient ]!", remain to process [ 0 ]
3702 ms passed. Model is unloaded, releasing resources to exit the application ...
Exit application, check the logs for details!

    The specific application's output will vary based on its functionality and implementation.

Ensure that you are in the correct directory and provide the correct path to the application you want to run. Adjust the command accordingly for different applications within the bin directory.

By following these steps, you will be able to run the applications compiled from the AREG SDK in WSL and view their output in the WSL Terminal.

Help us to make docs greater: See something is wrong, unclear or need a help? Submit a change, open a discussion or ask AREG SDK community a question.

2023 © Aregtech, www.aregtech.com, email: info[at]aregtech.com

Quick links

  1. Clone source codes
  2. Preprocessor define symbols
  3. Software build
  4. Build with WSL
  5. AREG Logging System
  6. AREG Multicast Router
  7. Persistence Syntax
  8. Setup a Project

Help to make docs greater!

Clone this wiki locally