When you install software from source, it often ends up in various directories across your system (like /usr/local/bin, /usr/local/lib, etc.).

Over time, managing these files can become a hassle, especially if you want to remove or update a package. GNU Stow addresses this problem by organizing software installations in a clean and maintainable way.

In this detailed tutorial, we will discuss what GNU Stow is and how to use GNU Stow to install and manage software from source in an efficient and organised way in Linux.

What is GNU Stow?

GNU Stow is a symlink farm manager that helps manage the installation of software packages in Linux and Unix-like systems. It uses symbolic links to simplify the management of software installed from source code.

The primary purpose of GNU Stow is to help organize files and directories in a way that allows for easy management and maintenance.

It works by creating symbolic links in a parent directory to the files and directories in the installed packages.

This approach allows multiple packages to coexist in the same directory without interfering with each other, as each package's files are kept separate and are linked into place as needed.

GNU Stow is particularly popular among users who prefer to manage their own software installations and configurations, as it provides a clean and efficient way to keep everything organized.

It is also commonly used in conjunction with version control systems to manage configuration files and other resources that need to be shared across different machines or environments.

GNU Stow is a free, open-source tool, and part of the GNU project.

How GNU Stow Works

Stow assumes each software package is stored in its own directory. For example, you might have /usr/local/stow/package1 and /usr/local/stow/package2.

When you "stow" a package, Stow creates symbolic links from the package directory to the appropriate locations in your filesystem. For example, it might link /usr/local/stow/package1/bin/program to /usr/local/bin/program.

To install a package, you navigate to the directory containing the stow-managed directories and run stow package1. This creates the necessary symbolic links. To uninstall, you run stow -D package1, which removes the links.

GNU Stow Features

Key features of GNU Stow include:

1. Symbolic Links: Stow creates symbolic links to the files and directories of each package, pointing to their actual locations. This ensures that the files appear to be in the correct place without actually being there, which helps avoid conflicts between different packages.
2. Package Management: It is useful for managing software that is installed in user-specific or system-wide directories, especially when dealing with configuration files or scripts that need to be in specific locations.
3. Easy Upgrades and Removals: Upgrading or removing a package managed by Stow is straightforward, as it involves simply updating or deleting the package's directory. Stow automatically updates or removes the corresponding symbolic links.
4. Flexible Configuration: Users can configure Stow to suit their needs, including specifying the target directory for the links and handling different types of files.

Advantages

Using GNU Stow in your workflow brings the following three major advantages:

1. Simplifies Package Management:

You can easily install, update, and remove software packages. You can even install multiple versions of same package from source.

2. Avoids Conflicts:

Since each package is in its own directory, there’s less chance of file conflicts.

3. Reproducibility:

Makes it easier to reproduce and document the software environment.

Use Case

GNU Stow is useful for developers who compile and install software from source regularly. It’s also handy for managing dotfiles (configuration files), as it can maintain a consistent setup across different systems.

General Usage

To install a package:

cd /usr/local/stow
stow package1

To uninstall a package:

cd /usr/local/stow
stow -D package1

By using GNU Stow, you can keep your system organized and reduce the complexity of managing software installations.

Install Software from Source using GNU Stow

For the demonstration purpose, we will see how to install the latest version of curl using GNU Stow on a Linux system.

1. Update Your System:

Ensure your system package database is up-to-date.

sudo apt update   # For Debian/Ubuntu-based systems
sudo yum update   # For CentOS/RHEL systems
sudo dnf update   # For Fedora systems
sudo pacman -Syu  # For Arch Linux systems

2. Install Required Development Tools:

Install the necessary development tools if they are not already installed.

sudo apt install build-essential   # Debian/Ubuntu
sudo yum groupinstall "Development Tools"   # CentOS/RHEL
sudo dnf groupinstall "Development Tools"   # Fedora
sudo pacman -S base-devel   # Arch Linux

You will also need to install the OpenSSL development libraries if you want to compile curl with the OpenSSL backend. For example on Debian-based systems, you can install OpenSSL development libraries using command:

sudo apt install libssl-dev

If you want to compile curl with the GnuTLS backend, install the following on a Debian-based systems:

sudo apt install libgnutls28-dev libgnutls30

3. Install GNU Stow:

Ensure GNU Stow is installed.

sudo pacman -S stow     # Arch Linux
sudo apt install stow   # Debian/Ubuntu
sudo yum install stow   # Older CentOS/RHEL
sudo dnf install stow   # Latest Fedora/RHEL/AlmaLinux/Rocky Linux

4. Download and Extract curl Source Code:

Download the latest Curl source code from its official releases page and extract it.

wget https://github.com/curl/curl/releases/download/curl-8_8_0/curl-8.8.0.tar.gz
tar xvf curl-8.8.0.tar.gz

5. Configure the Build with the Prefix:

Cd into the extracted directory:

cd curl-8.8.0

Configure the Build with the TLS backend and installation directory to be managed by GNU Stow.

./configure --with-ssl --prefix=/usr/local/stow/curl-8.8.0

If you want to configure Curl with GnuTLS, use this command instead:

./configure --with-gnutls --prefix=/usr/local/stow/curl-8.8.0

6. Compile the Software:

make

7. Install the Software:

sudo make install

8. Use GNU Stow to Manage the Installation:

Change to the stow directory and use stow to manage the installation.

cd /usr/local/stow
sudo stow curl-8.8.0

9. Verify the Installation:

Verify that Curl is correctly installed and accessible.

curl --version

Sample Output:

curl 8.8.0 (x86_64-pc-linux-gnu) libcurl/8.8.0 OpenSSL/1.1.1w zlib/1.2.11
Release-Date: 2024-05-22
Protocols: dict file ftp ftps gopher gophers http https imap imaps ipfs ipns mqtt pop3 pop3s rtsp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS HSTS HTTPS-proxy IPv6 Largefile libz NTLM SSL threadsafe TLS-SRP UnixSockets

By following these steps, you will have installed the latest version of curl using GNU Stow, ensuring a clean and organized installation.

Update Software from Older Version

To update from an earlier version of Curl (e.g., 8.7.1) to the latest version (e.g., 8.8.0) using GNU Stow, you can follow these steps:

1. Uninstall the Old Version:

First, you need to uninstall the old version of Curl. Since you installed it using GNU Stow, you can simply unstow it.

cd /usr/local/stow
sudo stow -D curl-8.7.1

And then, go back to your home directory:

cd

2. Download and Extract the Latest Curl Source Code:

Download the latest version of Curl and extract it.

wget https://github.com/curl/curl/releases/download/curl-8_8_0/curl-8.8.0.tar.gz
tar -xzf curl-8.8.0.tar.gz
cd curl-8.8.0

3. Configure and Build the Latest Curl:

Configure the build environment and compile the latest version of Curl.

./configure --with-ssl --prefix=/usr/local/stow/curl-8.8.0
[or]
./configure --with-gnutls --prefix=/usr/local/stow/curl-8.8.0
make
sudo make install

4. Use GNU Stow to Manage the New Installation:

cd /usr/local/stow
sudo stow curl-8.8.0

5. Verify the Update:

Verify that the latest version of Curl is correctly installed and accessible.

curl --version

6. Remove the Older Version (Optional):

While GNU Stow will unlink the old version, it won't remove the old directory. To fully remove the old version of Curl after installing the new one:

sudo rm -rf /usr/local/stow/curl-8.7.1

This process ensures that you can easily manage and update multiple versions of Curl using GNU Stow, making it convenient to switch between different versions if needed.

Advanced Usage of GNU Stow

GNU Stow offers several advanced options and features that can enhance its utility and flexibility. Here are some of them:

1. Relocatable Packages:

Stow allows you to create packages that can be relocated without changing their contents. This means the same package can be stowed in different places without modifying the files.

You can use the --dir and --target options to specify the source directory of the packages and the target directory where the symlinks should be created.

Example:

stow --dir=/path/to/packages --target=/usr/local package_name

2. Simulating Stow Operations:

Before making actual changes, you can simulate stow operations to see what would happen. This helps avoid mistakes.

We can use the -n or --no option to perform a dry run.

Example:

stow -n package_name

3. Verbose Output:

Get detailed information about what stow is doing. This can be useful for debugging or understanding the actions being performed.

Use the -v or --verbose option to view detailed information.

Example:

stow -v package_name

4. Ignoring Files and Directories:

You can tell Stow to ignore certain files or directories within the package.

Create a .stow-local-ignore file in the package directory listing the files or directories to ignore.

Example:

Create a .stow-local-ignore file with the following content:

.git
README.md

5. Restow and Destow:

Restow: This operation first unstows the package and then stows it again. It’s useful for refreshing symlinks after making changes to the package contents.

Usage:

stow -R package_name

Destow: This operation removes the symlinks created by stow.

Usage:

stow -D package_name

6. Adopting Pre-existing Files:

Stow can adopt files that already exist in the target directory. This is useful for bringing existing files under stow’s management without having to move them manually.

Use the --adopt option.

Example:

stow --adopt package_name

7. Conflict Handling:

Stow can detect and handle conflicts between packages.

Use the --override option to forcefully overwrite existing files.

Example:

stow --override package_name

8. Custom Stow Directories:

You can specify custom directories for stowing packages, which allows for more flexibility in organizing your software.

Use the --dir option to specify the source directory and --target to specify the target directory.

Example:

stow --dir=/custom/source --target=/custom/target package_name

For a complete list of options, you can refer to the stow man page:

man stow

Example: Using Multiple Options

Here’s an example that combines several advanced options:

stow --dir=/path/to/packages --target=/usr/local --verbose --no --adopt --override package_name

Here's a breakdown of each option:

• --dir: Specifies the source directory of the package.
• --target: Specifies the target directory for the symlinks.
• --verbose: Provides detailed output of the operation.
• --no: Performs a dry run to simulate the operation.
• --adopt: Adopts pre-existing files in the target directory.
• --override: Forcefully overwrites existing files.

GNU Stow Cheat Sheet

1. Stow a package:

stow package_name

Creates symlinks for package_name in the parent directory.

2. Unstow a package:

stow -D package_name

Removes symlinks for package_name.

3. Restow a package:

stow -R package_name

Unstows and then re-stows package_name.

4. Specify source directory:

stow --dir=/path/to/packages package_name

Sets the source directory where packages are located.

5. Specify target directory:

stow --target=/path/to/target package_name

Sets the target directory where symlinks should be created.

6. Simulate the operation (dry run):

stow -n package_name

Performs a dry run without making any changes.

7. Verbose output:

stow -v package_name

Provides detailed output of the operation.

8. Adopt pre-existing files:

stow --adopt package_name

Adopts existing files in the target directory.

9. Force override conflicts:

stow --override package_name

Overwrites existing files in the target directory.

10. Ignore specific files or directories:

Create a .stow-local-ignore file in the package directory with the files or directories to ignore.

Example .stow-local-ignore content:

.git
README.md

11. Stow a package from a custom directory to a custom target:

stow --dir=/path/to/packages --target=/path/to/target package_name

12. Unstow a package and remove its directory:

stow -D package_name
sudo rm -rf /usr/local/stow/package_name

13. Restow a package with verbose output:

stow -Rv package_name

14. Adopt existing files into Stow management:

stow --adopt package_name

15. Dry run to check what would happen:

stow -n package_name

Summary of Options

• -D / --delete: Unstows a package by removing its symlinks.
• -R / --restow: Unstows and re-stows a package.
• -n / --no: Dry run (simulate the operation).
• -v / --verbose: Verbose output.
• --dir: Specify the source directory.
• --target: Specify the target directory.
• --adopt: Adopt pre-existing files.
• --override: Force overwrite of existing files.

Example Workflow

1. Stow a new package:

cd /usr/local/stow
sudo stow package_name

2. Unstow an old package and remove its directory:

sudo stow -D old_package_name
sudo rm -rf /usr/local/stow/old_package_name

3. Restow a package after making changes:

cd /usr/local/stow
sudo stow -R package_name

4. Adopt existing files in the target directory:

cd /usr/local/stow
sudo stow --adopt package_name

5. Simulate stowing a package to check for errors:

cd /usr/local/stow
stow -n package_name

Frequently Asked Questions

Q: What is GNU Stow?

A: GNU Stow is a handy tool for Linux that helps you manage software you compile from source code. Instead of directly installing the software in system directories like /usr/local, Stow keeps things organized by:

• Storing the software in its own directory: This prevents conflicts with other programs and keeps your system clean.
• Creating symbolic links: These links act like shortcuts, pointing to the actual program files in their separate directories. From your perspective, the software appears installed normally, but Stow manages the links behind the scenes.

Q: How do I install GNU Stow?

A: GNU Stow can typically be installed via your distribution's package manager. For example, on Debian-based systems, you can install it using:

sudo apt-get install stow

On Red Hat-based systems, you can use:

sudo dnf install stow

Q: How do I use GNU Stow to manage packages?

A: To use GNU Stow, you first need to install your software into a directory structure that Stow can manage. For example, if you have a package in /usr/local/stow/mypackage, you can make it appear in /usr/local by running:

cd /usr/local/stow
sudo stow mypackage

Q: How can I manage multiple versions of the same software with GNU Stow?

A: You can install each version of the software into its own directory under the Stow directory (e.g., /usr/local/stow/mypackage-1.0 and /usr/local/stow/mypackage-2.0). To switch between versions, simply unstow the current version and stow the desired version:

cd /usr/local/stow
sudo stow -D mypackage-1.0  # Unstow version 1.0
sudo stow mypackage-2.0     # Stow version 2.0

Q: What happens if there are conflicts or overlaps between packages?

A: GNU Stow will warn you if there are conflicts or overlaps between the packages you are trying to stow. You can resolve these conflicts by manually adjusting the directory structure or by using the --adopt option to let Stow take ownership of the conflicting files.

Q: How do I uninstall a package managed by GNU Stow?

A: To uninstall a package, you simply need to unstow it:

cd /usr/local/stow
sudo stow -D mypackage

This will remove the symlinks created by Stow, effectively "uninstalling" the package.

Q: Can I use a different directory for Stow?

A: Yes, you can specify a different directory for Stow using the -d option. For example, if you want to use /opt/stow as your Stow directory, you can run:

sudo stow -d /opt/stow mypackage

Q: Are there any advanced options or features in GNU Stow?

A: Yes, GNU Stow has several advanced options, including:

• --ignore=PATTERN: Ignore files matching a specific pattern.
• --defer=PATTERN: Defer handling of files matching a specific pattern.
• --adopt: Adopt existing files into the Stow package.
• --no-folding: Disable directory folding.

Q: What should I do if GNU Stow is not working as expected?

A: If you encounter issues, you can check the following:

• Ensure that the directories you are managing with Stow are correctly structured.
• Verify that there are no permission issues by running Stow with elevated privileges (sudo).
• Review the output of Stow for any warnings or errors.
• Consult the stow man page or the GNU Stow documentation for additional guidance.

Key Takeaways

GNU Stow is a useful tool for managing software installations and configurations.

• GNU Stow is a free and open source Symlink farm manager.
• It's primarily used to manage the installation of software packages, keeping them organized in separate directories.
• Stow creates symlinks from a central directory (usually /usr/local/stow) to the appropriate locations in the system directory tree.
• It's particularly helpful for managing dotfiles and keeping track of custom software installations.
• Stow allows for easy package management, installation, and removal without mixing files from different packages.

Conclusion

GNU Stow provides a user-friendly solution for managing software you compile yourself in Linux. It eliminates the hassle of scattered files and simplifies the update and removal process.

By creating symbolic links, Stow keeps your system organized and allows you to switch between different software versions effortlessly. Stow is quite useful for developers and testers who often install software from source in Linux.

If you're looking for a way to streamline your workflow with source-built programs, GNU Stow is a valuable tool to add to your Linux toolkit.

Resources:

• GNU Stow Website
• GNU Stow Documentation

Suggested Read:

• How To Remove Programs Installed From Source Using GNU Stow In Linux
• How To Find And Remove Unused Packages In Linux

Featured Image by GrumpyBeere from Pixabay.