Shipwright(3)

✨ NAME ✨

Shipwright — Best Practical Builder 💖

okay so real talk, bestie: this is the manual page for Shipwright, section 3, and it comes to you courtesy of User Contributed Perl Documentation. (also there's a lone new sitting at the very top of the original page before NAME, no idea, it's giving typo core, but we're leaving it exactly where it was 💅)

---

🌈 SYNOPSIS 🌈

$ export SHIPWRIGHT_SHIPYARD=fs:/tmp/fs
$ shipwright create
# import will take a while, enjoy your coffee!
$ shipwright import cpan:Jifty
$ cd /tmp/fs
$ ./bin/shipwright-builder --install-base /tmp/jifty

one liner doing the same thing:
$ shipwright-generate cpan:Jifty | perl - --install-base /tmp/jifty

one-liner queen behavior honestly 👑

---

🦋 DESCRIPTION 🦋

💭 Why use Shipwright?

Most software packages depend on other bits of software in order to avoid code repetition. and like… valid. except now you're installing one thing and it drags in a whole maze of dependencies, which is a genuine nightmare when the project is big and the dependency tree is deep. 😭

so Shipwright exists to help you bundle your software with all its dependencies — doesn't matter if they're CPAN modules or non-Perl modules from literally anywhere else. Shipwright makes the bundle work easy. periodt. ✨

🍼 Introduction

first time here? then bestie, Shipwright::Manual::Tutorial is probably a better place to start. no shame, we've all been there 🫶

🎨 Design

the idea of Shipwright is simple:

    sources                        shipwright factory
---------------------           ------------------------
|  all the separate |  import   |  shipyard             |  build
|  sources          |  =====>   |                       |  ====>
---------------------           ------------------------

     vessel (final product)
----------------------------------------------
| all packages installed with smart wrappers |
----------------------------------------------

sources go in, factory does its thing, vessel comes out. it's giving assembly line but make it cute 🏭💖

🚢 What's in a shipyard

🌱 shipyard after initialization

after initializing a shipyard, the files in the repository are:

bin/
    # used for building, installing and testing
     shipwright-builder
    # a utility for doing things such as updating the build order
     shipwright-utility

etc/
    # wrapper for installed bin files, mainly for optimizing the
environment
     shipwright-script-wrapper
    # wrapper for installed perl scripts
    shipwright-perl-wrapper
    # source files you can `source', for tcsh and bash, respectively.
    # both will be installed to tools/
    shipwright-source-tcsh, shipwright-source-bash
    # utility which will be installed to tools/
    shipwright-utility
    # set env bat for windows
    shipwright-windows-setenv.bat

inc/ # modules for shipwright itself

sources/      # all the sources live here

scripts/    # all the build scripts and dependency hints live here

shipwright/

    # branches note, see L<Shipwright::Manual::UsingBranches>
    branches.yml
    # flags note, see L<Shipwright::Manual::UsingFlags>
    flags.yml
    # test failures note
    known_test_failures.yml
    # cpan dists' module => name map
    map.yml
    # the actual build order
    order.yml
    # reference count note
    refs.yml
    # non-cpan dists' name => url map
    source.yml
    # sources' version
    version.yml

t/
    # will run this if with --only-test when build
    test

that's a lot of yml files and honestly? each one is iconic in its own way. 💅

📦 shipyard after import

after importing — say, cpan:Acme::Hello — both the sources and scripts directories will have a cpan-Acme-Hello directory. ✨

under scripts/cpan-Acme-Hello there are two files: build and require.yml.

🔨 build

configure: %%PERL%% %%MODULE_BUILD_BEFORE_BUILD_PL%% Build.PL --install_base=%%INSTALL_BASE%% --install_path lib=%%INSTALL_BASE%%/lib/perl5 --install_path arch=%%INSTALL_BASE%%/lib/perl5
make: %%PERL%% %%MODULE_BUILD_BEFORE_BUILD%% Build
test: %%PERL%% %%MODULE_BUILD_BEFORE_BUILD%% Build test
test install: %%PERL%% %%MODULE_BUILD_BEFORE_BUILD%% Build install
clean: %%PERL%% %%MODULE_BUILD_BEFORE_BUILD%% Build realclean

(yes i un-wrapped the lines so you can actually see them, they were all squished in the original 🙈)

each line is in the type: command format, and the command gets executed line by line — which is also true for t/test, fyi.

want to customize the build process for dists? go read Shipwright::Manual::CustomizeBuild. it's all in there 📖

📋 require.yml

build_requires: {}

conflicts: {}

recommends:
  cpan-Locale-Maketext-Lexicon:
    version: 0.15 requires: {}

this file spills all the hints needed so Shipwright can figure out the right build order. no cap 🧚

🛳️ vessel

after the cmd ./bin/shipwright-builder --install-base /tmp/vessel, we get a whole new directory structure, and that's what we call a vessel (/tmp/vessel). 🌊

---

👀 SEE ALSO 👀

• Shipwright::Manual

---

👑 AUTHORS 👑

• sunnavy <sunnavy@bestpractical.com>

---

💜 LICENCE AND COPYRIGHT 💜

Shipwright is Copyright 2007-2015 Best Practical Solutions, LLC.

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🫶

---

and that's the whole page bestie!! this one shipped with perl v5.42.0, dated 2025-07-25, and it's Shipwright(3) through and through. go build something cute, mwah 💖🎀🦋