WSL Development Environment: Fast Setup with Custom Debian

Introduction

I will introduce how to efficiently build a development environment by importing a customized Debian^[1] into WSL^[2].
This method allows for the rapid construction of a consistent development environment, enhancing development efficiency.

1. Overview of the Debian Archive

A customized Debian archive is a tar archive^[3] containing development tools and customized settings.
Importing this significantly reduces the time required to build a development environment.

The archive used in this article was pre-configured in the Environment Setup Article Summary.

To remove personal credentials, dotfiles^[4] are used from direct downloads.

2. Overview of WSL Import

When importing a Debian archive into WSL, the wsl --import^[5] command is used.
This makes it easy to replicate or migrate environment settings.

2.1. wsl import Command Line

The wsl --import command imports a Linux distribution in tar archive format into WSL. It then reproduces the state of the Linux distribution at the time of export.

By using this command, you can quickly build an environment while maintaining existing settings.

The wsl --import command is executed in the following format:

wsl --import <Distribution> <ImportDirectory> <tarArchive>

The meaning of each parameter is as follows:

• <Distribution>:
  The name of the Linux that WSL starts, usually the Linux distribution name
• <ImportDirectory>:
  The directory where the distribution is imported; it must be created before importing
• <tarArchive>
  The tar archive exported by wsl

Note:
The import directory must be specified as an absolute path.

3. Importing Customized Debian

Here are the steps to download the customized Debian archive and import it into WSL. This will allow users to proceed with the work without hesitation.

3.1 Downloading the Debian Archive

The Debian archive can be downloaded from PublicArchives.

Follow these steps to download the Debian archive:

1. Access [PublicArchives]
   

2. Select Download from the menu on the right side of custom-debian.tar-x.y.z.7z
   

3. Click the [Download anyway] button in the dialog to download
   

Note:
An error appears because the file cannot be scanned for viruses. You can ignore it.

This completes the download of custom-debian.tar-x.y.z.7z.

3.2 Extracting the Debian Archive

Extract the downloaded Debian archive using 7zip^[6].
7zip is a powerful tool capable of handling various compressed file formats, including the 7z format.
Use this command to extract the downloaded 7z file into a format compatible with WSL.

Run the following command to extract it:

1. Extraction using the 7z command:
   Extract the Debian archive with the 7z x command.

   7z x custom-debian.tar-x.y.z.7z
   

   If the execution result looks like the following, the extraction was successful.

    .
    .
   Everything is Ok
   
   $
   

3.3 Configuring the Import Directory

The import directory must be a directory that the user can manage.
The import directory follows the XDG Base Directory^[7] specification (a standard for file placement in Linux systems).
Therefore, the Debian import directory will be set to /~/.local/share/wsl/debian.
By following the XDG Base Directory specification, WSL files are placed under .local, which increases security.

Follow these steps to create the import directory:

1. Creating the import directory
   Create the import directory.

   mkdir ~/.local/share/wsl/debian
   

This completes the configuration of the import directory.

3.4 Importing the Debian Archive

If extraction was successful, the custom-debian.tar file should have been created.
To import the Debian archive, run the following command in PowerShell:

1. Importing Debian

   wsl --import Debian C:\Users\<myaccount>\.local\share\wsl\debian .\custom-debian.tar  # Replace <myaccount> with your own account name
   

   The execution result will be as follows:

   
   Importing in progress. This process may take a few minutes.
   The operation completed successfully.
   
   $
   

If it outputs "The operation completed successfully." as shown above, the import was successful.

4. Changing the Default User Account

This section explains how to change the default user account.
This allows you to configure the environment with your own account.

4.1 Changing the User Account

You need to change the user account from pwruser to your own account.
The change is performed using the move_useraccount.sh script.
The script is executed as follows:

move_useraccount.sh <myaccount>

Follow these steps to change the account:

1. Changing the user account

   move_useraccount.sh <myaccount>   # Replace <myaccount> with your own account
   

This completes the change of the user account.

4.2 Setting the Default User

Change the default user at startup from root to your own account.
Edit /etc/wsl.conf with an editor and configure it as follows:

/etc/wsl.conf

## User settings
[user]
default=<myaccount>    # Replace <myaccount> with your own account.

In this way, set default to your account in the [user] section of /etc/wsl.conf.
As a result, the default user becomes your account.

After restarting WSL, it will be changed to log in with your account when Debian starts.

4.3 Setting the Password

Set a strong password for your account to maintain security.
To ensure account security, please set a strong password. Recommended passwords are complex, long, and difficult to predict.

In bash, run the following command to set the password:

passwd <myaccount>  # Replace <myaccount> with your own account.

The execution result will be as follows:

$ passwd <myaccount>
New password:
Retype new password:
passwd: password updated successfully

$

This completes the password setting.

5. Restarting WSL

With the above steps, the WSL configuration is complete.
After completing the setup, restart WSL to apply the new settings. This ensures the customized Debian environment works correctly.

Run the following commands to restart WSL:

1. Shutting down WSL
   Shut down WSL.

   wsl --shutdown
   

2. Starting Debian
   Select Debian in Windows Terminal and start Debian on WSL.

After restarting, Debian will operate in its newly customized state and log in with the user's account.

6. Additional Settings

By following the steps up to restarting WSL, you have successfully built the Debian development environment.
In this chapter, I will introduce how to manage Debian environment settings using a version control system.

6.1 Integrating dotfiles

If existing dotfiles exist, you cannot clone them with git.
Therefore, delete the existing dotfiles and then integrate the latest version.

Follow these steps to delete the existing dotfiles and integrate the latest version:

1. Delete subdirectories under /opt/:
   Delete /opt/bin and /opt/etc to make them symbolic links.
   Run the following command:

   sudo rm -fr /opt/etc /opt/bin
   

2. Delete dotfiles:
   Delete the dotfiles directory under ~/.local/.
   Run the following command:

   rm -fr ~/.local/dotfiles
   

3. Integrating dotfiles:
   Follow Environment Management Using dotfiles to integrate the dotfiles.

This completes the integration of dotfiles.

6.2 Reinstalling the what Command

The what command^[8] is a utility that parses specific comments in shell scripts or configuration files and outputs the file's summary or version.

Follow these steps to reinstall the what command:

1. Reinstalling the what command
   Follow Script Management with the what Command to reinstall the what command.

Conclusion

This completes the setup of the customized Debian.
Use this article as a reference to quickly build development environments tailored to individual projects and enjoy an efficient development experience.

So then, Happy Hacking!

References

Websites

• Basic commands for WSL: https://learn.microsoft.com/en-us/windows/wsl/basic-commands
• Import any Linux distribution to use with WSL: https://learn.microsoft.com/en-us/windows/wsl/use-custom-distro
• Environment Setup Article Summary: https://zenn.dev/atsushifx/articles/wsl2-debian-setup-matome
• Environment Management Using dotfiles: https://zenn.dev/atsushifx/articles/wsl2-debian-dotfiles
• what command: https://raw.githubusercontent.com/atsushifx/agla-shell-utils/main/agla/what

脚注

1. Debian: One of the Linux distributions.

2. WSL (Windows Subsystem for Linux): A subsystem for running Linux environments on Windows.

3. tar archive: A standard format for bundling multiple files/directories in UNIX/Linux.

4. dotfiles: A repository for managing UNIX/Linux configuration files, or the configuration files themselves.

5. wsl --import: A command for importing Linux distributions into WSL.

6. 7zip: A file archiving, compression, and extraction tool compatible with 7z and zip formats.

7. XDG Base Directory: A standard directory structure for managing configuration and data files in Linux systems.

8. what command: A command that outputs summaries of shell scripts or configuration files.