Date: March 9, 2026
pkgtools
==========
INTRODUCTION
===============
The "pkgtools" (note - its plural) package is the core package used by
Nakshatra Linux, which provides tools for its local package management.
The primary utilities (other than pkgdiff and pkgtool) are :
1. installpkg
2. removepkg
3. upgradepkg
4. explodepkg
5. makepkg
The npkg tool used to fetch/remove/install/upgrade packages from a online repository
uses the above scripts internally to manage software on the system.
Key Attributes:
- No Internet Required: Operates entirely on local files.
- No Dependency Resolution: It will not download missing libraries for you. (that is managed via a external given script)
Package Managment
===================
Nakshatra Systems packages can be found with any of the following extensions:
tbz - Nakshatra Systems package archive compressed using bzip2
tlz - Nakshatra Systems package archive compressed using lzip
tgz - Nakshatra Systems package archive compressed using gzip
txz - Nakshatra Systems package archive compressed using xz
The reason for the various package formats is the evolution of compression tools.
The primary format/extension of Nakshatra Linux packages is txz.
txz is the current standard for official packages because of the slightly better compression rate.
Dependency Tracking
=====================
Nakshatra Linux like its parent distro - slackware , does not automatically track dependencies and install dependencies
when you install a package. One of the reasons is to avoid dependency hell.
installpkg - This is used to install a new package.
removepkg - This is used to remove a package from your system.
upgradepkg - upgradepkg upgrades a package from an older version to a newer one. It does this by installing the new package
onto the system, and then removing any files from the old package that aren't in the new package.
explodepkg - This tool uncompresses and extracts package into your current directory so the contents can be reviewed prior
to installation.
pkgtool - pkgtool is a menu-driven package maintenance tool provided with the Nakshatra Systems Linux distribution.
It allows the user to install, remove, or view software packages through an interactive system.
Pkgtool can also be used to re-run the menu-driven scripts normally executed at the end of a Nakshatra Systems installation.
makepkg - This application is used to create a new package from the contents of your current directory.
1. Install package
=====================
The installpkg command is part of the Nakshatra Systems Linux pkgtools package management system.
It is a low-level utility used to install a local package file (.txz) directly into the system.
Unlike modern package managers (apt, dnf, pacman, npkg), it does not resolve dependencies automatically.
We need to ensure that all necessary dependencies are met before installing a package.
It simply installs the package contents.
Below is a detailed explanation of the command and what happens internally.
To install a package using installpkg, navigate to the directory containing the .tgz or .txz package file and execute:
installpkg <package.txz>
Internal Workflow of installpkg
When you run installpkg, the system performs three major operations:
- Extraction
- Post-Installation Script Execution
- Package Registration
--------------------------------------------------------------------------------
A] EXTRACTION Phase
--------------------------------------------------------------------------------
The package is uncompressed and extracted directly into the root filesystem (/).
Example package contents:
usr/bin/vim
usr/share/vim/
usr/man/man1/vim.1.gz
etc/vimrc
install/doinst.sh
Command internally executed (conceptually):
tar -xvf package.txz -C /
This means:
Option Meaning
-x extract
-v verbose
-f file
-C / extract into root
Result
Files are placed into the appropriate system directories:
--------------- ------------------
File in package Installed location
--------------- -------------------
usr/bin/vim /usr/bin/vim
usr/share/vim /usr/share/vim
etc/vimrc /etc/vimrc
So the package essentially merges its contents into the system filesystem.
Important Note
If a file already exists, it will be overwritten.
Nakshatra Systems relies on package logs to track installed files.
B. POST-INSTALL Script Execution
--------------------------------------------------------------------------------
Many packages include a script:
install/doinst.sh
After extracting files, installpkg automatically executes this script.
Purpose
The script performs additional configuration tasks that cannot be handled by simple file extraction.
Typical Operations
-------------------
Task Example
---- -------
Create symlinks ln -s
Update icon cache gtk-update-icon-cache
Update shared library cache ldconfig
Fix permissions chmod
Update/add configuration .new config files
Sample doinst.sh
------------------
#!/bin/sh
# Update shared library cache
/sbin/ldconfig
# Create symbolic link
ln -sf vim /usr/bin/vi
So, when installpkg runs, it automatically executes:
sh install/doinst.sh
This ensures software works correctly after installation.
c. Package Registration
--------------------------------------------------------------------------------
After installation, the package is registered in the system's package database
located in
/var/log/packages/
Each installed package creates a metadata log file.
Example: /var/log/packages/vim-9.0-x86_64-1
Each file corresponding to the installed packages contains :
-------------------------------------------------------------
1. PACKAGE DESCRIPTION
PACKAGE NAME: vim-9.0-x86_64-1
PACKAGE LOCATION: ./Nakshatra Systems/ap
PACKAGE SIZE: 12 MB
PACKAGE DESCRIPTION:
vim: Vim (Vi IMproved text editor)
vim: Vim is an advanced text editor...
2. FILE LIST INSTALLED
This list allows Nakshatra Systems to track every file installed by the package.
Example:
usr/bin/vim
usr/share/vim/vimrc
usr/man/man1/vim.1.gz
etc/vimrc
3. INSTALLATION TIMESTAMP
This helps in auditing, troubleshooting, upgrades, and removal.
Example:
FILE LIST:
./
usr/
usr/bin/
usr/bin/vim
Other pkgtools commands use this database to function:
COMMAND FUNCTION
------- --------------------------------------------------
removepkg Removes files using the stored file list
upgradepkg Replaces the old version using the database
pkgtool Text UI package manager for system maintenance
EXAMPLE REMOVAL:
Command: removepkg vim
Action: It reads /var/log/packages/vim-9.0-x86_64-1 and deletes
all files listed therein.
================================================================================
2] Removing Installed packages - removepkg
================================================================================
The removal process is precise and follows a three-step logic:
1. CHECK INSTALLATION
To verify if a package exists, the system checks for a matching entry
in /var/log/packages/.
2. THE REMOVAL PROCESS (Deep Dive)
A. LOOKUP: Locates the specific package manifest (log file) in
/var/log/packages/ to identify all associated files.
B. SELECTIVE DELETION: Deletes the files listed in the manifest.
CRITICAL: It will NOT delete a file if it is currently being used
by another installed package (Shared Library Protection). This
prevents system breakage by ensuring dependencies remain intact.
C. CLEANUP: Once files are deleted, it removes the manifest log file,
officially removing the software from all system records.
EXAMPLE REMOVAL:
Command: removepkg vim
Action: Reads /var/log/packages/vim-9.0-x86_64-1
Deletes listed files
Updates the log file.
NOTE
When deleting files, removepkg will analyze the contents of the other packages installed on your system,
and will only delete the files that are unique to the package being removed. Similarly, the installation scripts
for all the other packages will be considered when deciding whether or not to delete symbolic links from the package.
Removing a package (as well as installing one) can be a dangerous undertaking.
For this reason, there is the -warn option available. When you use this, removepkg will not actually remove any files or links,
but will output a detailed report of what it would do if you actually did remove the package. It's suggested that you do
this (and maybe pipe the output to less ) before removing packages to make sure you've backed up anything that might be important.
When removing a package, its original file index will be moved from /var/lib/pkgtools/packages to /var/log/pkgtools/removed_packages.
Like‐wise, its installation script will be moved from /var/lib/pkgtools/scripts to /var/log/pkgtools/removed_scripts.
removepkg supports /bin/sh compatible uninstall scripts. If the package shipped with an uninstall script, it will be run after
the package is removed. If present, the uninstall script resides in the /var/lib/pkgtools/douninst.sh/ directory and has the same
full name as the package (without the extension).
eg: A package named foo-1.0-noarch-1.txz might contain an uninstall script named: /var/lib/pkg‐tools/douninst.sh/foo-1.0-noarch-1
A package's uninstall script may either ship directly in /var/lib/pkgtools/douninst.sh/ as the correctly-named file, or it may ship
as /install/douninst.sh. In the latter case, it will be renamed and placed in /var/lib/pkgtools/douninst.sh/ by installpkg.
3. Packge Upgrades (upgradepkg)
================================================================================
The upgradepkg tool upgrades a package(s) with the new .txz file.
--------------------------------------------------------------------------------
THE "UPGRADE" LOGIC
--------------------------------------------------------------------------------
Unlike some package managers that simply overwrite files, 'upgradepkg' follows
a sophisticated "Install-then-Clean" process to ensure system stability:
1. IDENTIFICATION
The tool identifies the currently installed version by searching the
manifests in /var/log/packages/.
2. INSTALLATION
It installs the new version of the package. If files have the same name,
the new versions overwrite the old ones.
3. SELECTIVE CLEANUP (The "Ghost File" Prevention)
It compares the file list of the old package against the new one.
Any files belonging to the old version that are NOT present in the
new version are deleted.
Benefit: This prevents "file clutter" or "ghost files" (stale libraries
or binaries) from lingering on your system.
--------------------------------------------------------------------------------
EXAMPLE COMMANDS:
--------------------------------------------------------------------------------
# Upgrade a single local package:
upgradepkg vim-9.1-x86_64-1.txz
# Upgrade a package, installing it if it isn't already there:
upgradepkg --install-new vim-9.1-x86_64-1.txz
4. DIFFERENCE BETWEEN UPGRADEPKG VS. INSTALLPKG
================================================================================
FEATURE UPGRADEPKG INSTALLPKG
------- ---------- -----------------------
Configuration Preserves .new files Might delete configs
Downtime Minimal (files replaced) Software is missing between steps
Cleanup Automatic "ghost" removal Manual check required
Safety High Moderate
NOTE : DO NOT use upgradepkg to upgrade kernel packages on a live system, as you might brick the system.
Always use installpkg after downloading the kernel via npkg , verify and test the kernel. Then finally
after you are convinced that the new kernel resolves all problems , remove the old kernel.
You could also keep the old kernel as a backup assuming you have space.
5. LISTING PACKAGE CONTENTS (Without Extraction)
================================================================================
There are two primary ways to view the file list of a Nakshatra Systems .txz package
before deciding to install it.
-------------------------------------------------------------------------------
METHOD 1: Using 'tar' (The Standard Way)
--------------------------------------------------------------------------------
Since .txz files are XZ-compressed tar archives, you can use the 'list'
function of the tar command.
COMMAND:
tar -tvf package-name.txz
FLAGS:
-t : List the contents of an archive
-v : Verbosely list files (shows permissions, size, and owners)
-f : Use the specified file
EXAMPLE:
tar -tvf vim-9.0-x86_64-1.txz | less
--------------------------------------------------------------------------------
METHOD 2: Using 'less' (The Quick Way)
--------------------------------------------------------------------------------
If your system has 'lesspipe' configured, you can simply "view" the binary file.
COMMAND:
less package-name.txz
ACTION:
This will automatically trigger a pre-processor that displays the
package metadata and the full file list in a searchable pager.
6. explodepkg
=================
Unlike 'tar', which only lists files, 'explodepkg' is a utility that physically
unpacks the entire package into your current directory.
COMMAND:
explodepkg package-name.txz
HOW IT WORKS:
1. It uncompresses and extracts every file and folder inside the .txz.
2. It recreates the directory structure (e.g., ./usr, ./etc, ./install).
3. It does NOT execute doinst.sh.
4. It does NOT register the package in /var/log/packages/.
BEST FOR:
Manual inspection of files, editing a package before rebuilding it, or
extracting specific binaries to a non-standard location.
WARNING:
Always run this in an empty, temporary directory (e.g., /tmp/test/) to
avoid cluttering your current working folder with hundreds of files.
7. Creating a package (makepkg)
================================================================================
The 'makepkg' command converts a directory structure into a .txz package file
ready for installation.
a. PREPARATION: THE BUILD DIRECTORY
-------------------------------------
First, create a temporary "root" directory and place your files exactly where
they should go on a real system.
EXAMPLE STRUCTURE:
/tmp/my-pkg/
├── etc/
│ └── my-app.conf
├── usr/
│ └── bin/
│ └── my-app
└── install/
├── descr <-- (Mandatory: Package description)
└── doinst.sh <-- (Optional: Post-install script)
b. MANDATORY: THE descr FILE
------------------------------
Every package requires a 'descr' file inside the 'install/' directory.
It must follow this exact 11-line format:
# HANDY RULER (the next line is 72 characters long):
# ----+----+----+----+----+----+----+----+----+----+----+----+----+----+
my-app: My App (Short description)
my-app:
my-app: Longer description goes here. It can span several lines.
my-app: Keep descriptions concise and stay within the 72-character limit.
my-app:
my-app:
my-app:
my-app:
my-app:
my-app:
my-app:
c. COMMAND: THE makepkg WORKFLOW
-----------------------------------
Navigate into your build directory and run the command:
COMMAND:
cd /tmp/my-pkg/
makepkg -l y -c n ../my-app-1.0-x86_64-1.txz
COMMON OPTIONS/FLAGS:
-l y (Link Yes):
Converts existing symbolic links into a script in 'doinst.sh'.
This is the standard Nakshatra Systems way to handle symlinks.
-c n (Clean No):
Prevents the tool from resetting file permissions to 755/644.
Use this if you have specific permissions (like SUID) set manually.
-p (Preserve):
Preserves the ownership/permissions of the files exactly as they
exist in the build directory.
8. KEY DIRECTORIES & FILE TYPES
==================================
/var/log/packages/ : The "Database" of the system. Every file here is a
plain text list of files for a specific installed
package.
/var/log/scripts/ : Stores post-installation scripts that were executed
during the install process.
9. COMMON USE-CASES (MANUAL ADMINISTRATION)
================================================================================
Use-Case 1: Manual Software Installation
- Scenario: You have downloaded a custom build or a driver.
- Command: installpkg /path/to/driver-1.0-x86_64.txz
- Note: If the package already exists, this may cause file conflicts; use
upgradepkg instead for existing software.
Use-Case 2: Reinstalling a Corrupted Package
- Scenario: You accidentally deleted a binary in /usr/bin.
- Command: upgradepkg --reinstall package-name-version.txz
- Description: This forces the tool to overwrite all existing files with
fresh copies from the archive.
Use-Case 3: Checking if a Package is "Legally" Installed
- Scenario: You want to know if the system recognizes a piece of software.
- Command: ls /var/log/packages | grep <name>
- Description: If a file exists here, pkgtools can manage it. If not, the
software was likely installed "loosely" (e.g., via 'make install').
Use-Case 4: Batch Removal
- Scenario: Removing multiple packages at once.
- Command: removepkg package1 package2 package3
- Description: pkgtools accept multiple arguments, allowing for quick
system slimming.
Summary:
==========
To install a package:
# installpkg
or
# upgradepkg --install-new
To remove a package:
# removepkg
To upgrade a package:
# upgradepkg
To reinstall a package:
# upgradepkg --reinstall
================================================================================
10. CONCLUSION
================================================================================
While front-end tools provide convenience, pkgtools provide precision. They
allow the administrator to manage software in environments with no network
access and offer the ability to recover a system when high-level managers fail.
Always verify the integrity of a .txz file before using 'installpkg' to
ensure system stability.
For further help, please consult the man/manual page of the corresponding tool.
===============================================================================