Pinto:...duction(3pm)

📦
version 0.14000 · 7 versions
, in debian trixie, ubuntu resolute

💖 Pinto::Manual::Introduction 💖

okay so bestie, welcome to the manual page for Pinto::Manual::Introduction — it lives under the name Pinto:...duction(3pm) in the User Contributed Perl Documentation section, and it exists to answer one very big question: why does Pinto even exist?? 🦋

Spoiler: it's giving ✨*stability*✨ and it's giving ✨*toolchain*✨. Let's go.

✨ VERSION ✨

version 0.14 — yes queen, that's the one we're repping. 👑

🎯 GOALS 🎯

Pinto has two primary goals. Two. Iconic. Let's meet them:

  1. First — Pinto wants to fix the whole instability of the CPAN mirrors situation. Distribution archives are constantly getting added and removed from the CPAN, so if you use it to build a system or application, you may literally not get the same result twice. 😭 Not the vibe. Not it.
  2. Second — Pinto wants to encourage developers to use the CPAN toolchain for building, testing, and dependency management of their own local software, even if they never plan to release it to the CPAN. Local software deserves love too, fr fr. 🫶

So how does Pinto pull this off? By providing tools for creating and managing your own custom repositories of distribution archives. These repositories can contain any distribution archives you like, and they can be used with the standard CPAN toolchain. The tools also support various operations that let you deal with the common problems that come up during the development process. 💅

🕰️ PRIOR ART 🕰️

Over the last few years, the author personally used various combinations of those modules to create custom repositories at several organizations. But — and this is the tea ☕ — they always required some wrapping and/or glue to make them usable in the development process. And none of them seemed to be designed for extension. 🙈

What the author wanted was a tool that would:

  • work out-of-the-box
  • accommodate a wide range of use cases
  • scale to a large number of users
  • and grow in unexpected directions

And so, Pinto was born. 👶✨

🧩 COMPONENTS 🧩

The Pinto suite consists of several components, and all of them are included in this distribution. For most use cases, you should treat Pinto as an external application rather than a library that is integrated with your own application code. The author strongly recommends reading Pinto::Manual::Installing for tips on installing Pinto in the manner that is most appropriate for your needs. 📖 (Trust the process.)

🖥️ pinto

pinto is a command line application for creating and managing a Pinto repository. It works transparently with both remote and local repositories. However, repositories can only be created locally. ⚠️ Important. Don't forget it.

🌐 pintod

pintod provides a web service interface to your Pinto repository. This allows multiple (possibly remote) developers to manage a central repository. pintod also functions as the back end HTTP server for installer clients like cpan, cpanp, and cpanm. Serving cunt, literally. 💅

🛠️ Pinto and Pinto::Remote

Pinto and Pinto::Remote are the backend libraries for the pinto application. These are fairly stable, but not officially public and not documented. So if you want to hack on Pinto's internals, or create a new application around Pinto, you should start looking at these. 👀

🖧 Pinto::Server

Pinto::Server is the backend library for the pintod server application. It is still immature, and subject to radical change. 😬 It is based on raw Plack, so if you are brave you could wrap it with various middlewares to do interesting things. 🧚 (Brave. Very brave.)

📚 TERMINOLOGY 📚

Some of the terminology related to the CPAN is overloaded, which can lead to some confusion. So the author tries to define some of the key terms used throughout the documentation and the code. Buckle up, bestie. 🎀

📦 Archive

An "archive" is the file that developers ship, which contains all their application/library code, test cases, build scripts etc. Conversely, the archive is the file that users must fetch to install the application/library. Sometimes these are also referred to as "distributions".

🎁 Package

A "package" is something inside a distribution archive that provides some unit of functionality. In Perl, packages are declared with the package keyword. Some folks call these "modules", but the author tries to avoid that term because it is frequently misused. 😤

🔗 Prerequisite

A "prerequisite" is a package that must be installed for the sake of another distribution archive. Sometimes these are called "dependencies". Pinto does not currently distinguish between different flavors of prerequisites, such as "build-time" or "run-time" prerequisites.

🧠 CONCEPTS 🧠

🥞 Stack

All CPAN-like repositories have an index which maps the latest version of each package to the archive that contains it. Usually, there is only one such index. But with Pinto, there can be many indexes. Each of these indexes is called a "stack". 🎉

This allows you to create different stacks of dependencies within a single repository. So you could have a "development" stack and a "production" stack. Whenever you add a distribution or upgrade a prerequisite, it only affects one stack. Chef's kiss. 👑

📌 Pin

Only one version of a package can exist within a stack. So when you upgrade a package in a stack, the newer version replaces the older one. But sometimes, you discover that a newer version of a package is incompatible with your application, and you want to stay with the older version until you have an opportunity to fix the problem. 😩

In those situations, Pinto allows you to "pin" a particular version of a package to the stack. This prevents the package from being upgraded (either directly or as a prerequisite for some other package). Pinned and unbothered. 💅

🐣 WHY IS IT CALLED PINTO 🐣

Pinto is a name that the author sometimes uses for his son Wesley (as in "pinto bean"). 🫘

Daddy loves you, Wes! 💖

👀 SEE ALSO 👀

  • Pinto::Manual::Tutorial — Presents a narrative explanation of how to use Pinto. 📖
  • Pinto::Manual::QuickStart — Presents a condensed summary of pinto commands. ⚡

✍️ AUTHOR ✍️

Jeffrey Ryan Thalhammer <jeff@stratopan.com> 💜

This software is copyright (c) 2015 by Jeffrey Ryan Thalhammer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

and that's the whole page, bestie — this was perl v5.40.1 vibes, dated 2025-04-21, and it's the Pinto:...duction(3pm) page under User Contributed Perl Documentation. mwah 💋 stay stable, stay pinned, and go read the Tutorial. 🌈🦋💖

📦 where this page comes from