Vulpine Package Manager built in C!

C 99.7%
Shell 0.3%

Find a file

Taylor 4623209744 Merge pull request 'file-conflict' (#2 ) from charlie/vpm:fix/file-conflict into main Reviewed-on: vulpinelinux/vpm#2		2026-06-05 22:24:42 +01:00
build.sh	vpm initial	2026-06-05 20:01:35 +01:00
README.md	vpm initial	2026-06-05 20:01:35 +01:00
vpm.c	file-conflict	2026-06-05 22:08:06 +01:00

README.md

Vulpine Package Manager

A minimal, transparent package manager for Vulpine Linux and minimal systems.

A lightweight package management solution designed specifically for Vulpine Linux, built with the same philosophy of simplicity, transparency, and intentional design.

Overview

VPM is a statically-compiled package manager written in C, designed to work within minimal environments where traditional package managers like APT or Pacman would be impractical or inaccessible with ease. It manages basic package installation, removal, updates, and dependency resolution while maintaining the minimal footprint and understand-ability that defines Vulpine Linux.

Built for clarity over convenience, VPM allows you to understand exactly what your system contains and how software is managed from installation through removal.

Whilst simple, it is effective as a first iteration package manager for Vulpine Linux. Now open source it means others can contribute and optimise on it too; allowing other open source projects wanting to release to a wider audience the opportunity compile-and-release a .vpm package for simplified installing, updating and maintenance for their own users.

Features

Installation which deploys based on .vpm structure.
Attempts dependency resolution and automatic dependency checking with version constraints.
Conflict detection preventing incompatible packages from being installed simultaneously.
Package scripts supporting preinst, postinst, prerm, and postrm hooks.
Simplified file tracking using SHA256-based file integrity verification.
Configuration protection preserving modified config files during updates.
Virtual packaging where packages can provide names they don't directly supply.
Architecture support that tracks and manages architecture-specific packages, though .vpm and Vulpine Linux in themselves assume a 64-bit architecture.
Version constraint supports with classic >=, <=, >, < specifications.
Force removal which override dependency checks when necessary.

It is worth noting this is a minimalist package manager intended for Vulpine Linux, though other operating systems can install and run the ./build.sh to compile vpm onto their systems and begin making use of Vulpine Package Manager to deploy .vpm supported packages.

Usage

Your system may require you to use sudo vpm, ensure that after running ./build.sh the vpm actually exists in your /bin/ directory or it may fail to run.

vpm install <package>          Install a package
vpm remove [-f|--force] <pkg>  Remove a package
vpm list                       List installed packages
vpm search                     Search available packages
vpm get <package>              Download a package
vpm update <package>           Update a package
vpm c <directory>              Create a package from directory

Installation Example

These packages do not exist unless they are on https://vpm.vulpinelinux.org/packages

vpm install curl
vpm install openssl>=1.1.0,<=2.0.0

Removal Example

sudo vpm remove curl
sudo vpm remove -f conflicting-package

If you've downloaded a third-party .vpm you should move it into /var/lib/vpm/packages where you can then do sudo vpm install {package}, or sudo vpm install {full_package_name}.vpm.

Creating Packages

To create a .vpm package from a directory:

vpm c /path/to/package-dir

The directory must contain:

manifest for package metadata
files/ the package files
preinst, postinst, prerm, postrm scripts which are optional

Package Format

A .vpm file is a gzip-compressed tar archive containing:

package-name-1.0.0.vpm
├── manifest
├── files/
│   └── (your packaged files)
├── preinst (optional)
├── postinst (optional)
├── prerm (optional)
└── postrm (optional)

Manifest Format

name=package-name
version=1.0.0
arch=any
depends=libfoo>=1.0, libbar
provides=alternative-name
conflicts=incompatible-package

At the least any given manifest must provide name= and version=, an example of a complete minimal .vpm would be:

package-name-1.0.0.vpm
├── manifest
├── files/
│   └── var
│       └── lib
│           └── vpm
│               └── packages
│                   └── merk-0.051.950
│                       └── *

where-in merk-0.051.950 contains the files for your program.

The above example shows merk-0.051.950.vpm which will install to /var/lib/vpm/packages/merk-0.051.950/* as a result of its manifest and file structure. We strongly encourage you get packages/merk-0.051.950.vpm and extract it to see how the files build together if you want a live example, as the Vulpine team have reviewed this code before and can assure nothing auto-deploys during its installation throughvpm.

We split get and install so that you can get a .vpm before installing it to perform self-audits if you prefer. Offering a way for you to verify something yourself before installing you choose too. All get packages are saved to /var/lib/vpm/packages, install installs packages in there.

Making Your First `.vpm` Package.

We've done our best to keep it minimalist and simple - typically you can make a package by doing tar -czf {package-name}-{semantic_version}.vpm manifest files from the package root directory to compile a package. Replacing {package_name} and {semantic_version} with the ones in your manifest for example tar -czf cvsh-2.2.5.vpm manifest files.

If you are new to building a package, we get it can be a bit confusing.

You can run mkdir -p ./files/var/lib/vpm/packages/{program_name} && touch ./manifest replacing {package_name} with your program, borrowing from merk we could call this merk-0.051.950 and put your program files into that.

This will result in a file system similar to this:

├── files/
│   └── var
│       └── lib
│           └── vpm
│               └── packages
│                   └── {program_name}
├── manifest

If you're ever in doubt though, always reach out to the Vulpine team through discord or irc as we'd be happy to see you creating a .vpm package!

Databases

VPM maintains several databases in /var/lib/vpm/:

packages.db which stores installed packages and versions
files.db tracking files with SHA256 hashes
deps.db which supports dependency relationships
provides.db which is for virtual package mappings
conflicts.db to control package conflicts

Contributing

VPM follows Vulpine Linux contribution guidelines and we've made a revised summary for you...

Human-first is where code must be human-written and understood
Signed commits which clarifies that all contributions must be GPG-signed
Clear explanations in your pull-request, as changes must be well-documented
Test before pull-request where you must verify changes work before submitting

Before making changes, fork the repository and after cloning your fork, create a new branch.

If its a feature (such as adding, updating or changing an existing software) git checkout -b feature/your-feature-name

An example would be git checkout -b feature/update_handling

If your goal is to work on an issue you should use: git checkout -b fix/issue-reference-name

An example would be git checkout -b fix/accidental_overwriting

Your changes must be made in a dedicated branch (e.g. feature/your-feature-name) Once you've made changes, on your branch, please build and test:

./build.sh

Follow the flowchart as a general guide:

flowchart LR
    A[Build-and-run] --> B{Is your implementation working properly?}
    B -->|Yes| C[Great, take a screenshot and write documentation]
    B -->|No| D[Debug and try again]
    C --> E[Push to fork, pull request, supply docs, submit]
    D --> B

Ensure:

It does ./build.sh cleanly
Your feature works as intended
You haven't inadvertently broken something else
It can be built reliably time-again using ./build.sh

Avoid hard coding anything that risks being re-written by ./build.sh.

Pull Request Expectations

You've made the feature in git checkout -b feature/your-feature-name or similarly if its an issue fix as git checkout -b fix/issue-reference-name on your own fork, not on the main repository.
You must detail in at least one paragraph (short if you prefer) what your submission is resolving; describe what you changed and why, and how your code functions cleanly. You can keep it simple, but it must be understandable.

If we do not believe you wrote it, or understand it for yourself - it will be rejected.

Include any relevant logs or screenshots if applicable for documentation purposes.
Where possible include a reference link or documentation, so that others can learn from you and the project.

"Using auto-ai to make submissions, pushing clearly AI-generated code, repeated low-quality or unreviewed submissions may result in restricted contribution access. We are a human-first endeavour, we understand AI can be found in the IDE through to documentation in real-life and we cannot stop this but the more we minimise it here, in our project, the happier we all are." ~Charlie

You can then push your branch to your fork and open a Pull Request against the main repository ensuring your PR description follows the expectations outlined above, remembering to sign your commit we will reject any that are not signed.

Bare in mind when providing a -m for messaging to keep it short-and-simple for example git commit -m "patch for fixing {issue}", no one wants clunky and excessive messages.

Review Process

All contributions are:

Reviewed manually.
Tested for stability and compatibility.
Evaluated for alignment with project philosophy.

Submissions that cannot be clearly explained or maintained will be rejected. This is true for unsigned commits or those submitted on/to the main repository - it must go through your fork, and Pull Requested. We cannot overstate this enough. Vulpine Linux is built step-by-step including the packages we build-to-bake into it, with intent, so contributions should reflect that same mindset and set the bar for other developers to come after. We appreciate strongly well written and proper commits - it matters massively for reference and professionalism both on your part and ours.

Design Philosophy

VPM is intentionally minimal and we aim to follow the Vulpine Linux Philosophy:

Keep it transparent so others can understand exactly what it does by reading the code.
Stateless and low-complex meaning zero hidden logic.
Every operation should be traceable and audit-able.
Dependency-light means writing in a secure and minimal way.

We refuse to add convenience features that obscure how the system works. VPM should do package management simply and clearly.

Limitations

You're welcome to work on our limitations and expand the feature set and accessibility of VPM right now there is:

No graphical interface.
No package signing/verification. (we're setting up the API for that but welcome for staging in the code to be developed).
No full SAT solver for complex dependency resolution.
No package priority system.
Designed for single-user systems and servers inherently.

FAQ

Why is VPM so minimal?

Vulpine Linux is built intentionally. VPM reflects that philosophy so it does package management, nothing more. No bells, no whistles, no hidden complexity. Nothing that screams "this is in-audit-able on purpose", we want to keep it transparent and easy to understand.

Can I use VPM on other distributions?

VPM is designed for Vulpine Linux but could theoretically work on other minimal systems. However, it assumes a specific directory structure and minimal environment. Porting may require adaptation.

How do I handle package conflicts?

VPM will refuse to install conflicting packages. Use vpm remove -f to force removal if necessary, though this may break dependent packages.

What happens if an update fails?

VPM creates backups before updates. If installation fails, manual rollback may be required. We hope versions to come will improve rollback capabilities.

Are there security considerations taken during development?

All packages should come from trusted sources, ones added into our search API are verified first-hand by us and scanned for viruses and malware, though you can supply your own .vpm package from a third party and install that, it is not encouraged unless you trust the source.