build-cyrus-site

#!/usr/bin/env perl

use v5.36.0;

=head1 NAME

build-cyrus-site - rebuild the cyrusimap.org website

=head1 DESCRIPTION

Rebuilds the cyrusimap.org website (aka cyrusimap.github.io) from the RST
documentation in our various repositories and branches

=head1 SYNOPSIS

build-cyrus-site [options]

    Options:
    --publish   publish updates to upstream repository
    --help      show usage

=head1 OPTIONS

=over 4

=item B<--help>

Prints the usage information and exits.

=back

=cut

use File::Path qw(make_path);
use File::Spec::Functions;
use Getopt::Long::Descriptive;
use Pod::Usage;

my ($opt, $usage) = describe_options(
    '%c %o',
    [ 'help',     'display help and exit' ],
    [ 'only-dev', 'only build the dev version, and make it the root' ],
);

pod2usage(0) if $opt->help;

# A semi-persistent working directory
# (It's okay if this directory disappears, it will be remade automatically,
# but it's better if it doesn't disappear, so we don't have to do all these
# git clones every time)
my $workdir = File::Spec->rel2abs('.');
my $basedir = '/tmp/CYRUS_DOCS_BUILD_DIR';

my $builddir = canonpath("$basedir/cyrus-site");

my %repo = (
  sasl  => 'https://github.com/cyrusimap/cyrus-sasl.git',
  imapd => 'https://github.com/cyrusimap/cyrus-imapd.git',
);

my %source = (
    'cyrus-sasl' => {
        repo    => 'sasl',
        branch  => 'master',
        paths   => [ '/sasl' ],
    },

    cyrus_branch('master', [ '/dev' ]),

    archive_copy('2.5'),
    archive_copy('3.0'),
    archive_copy('3.2'),
    archive_copy('3.4'),
    archive_copy('3.6'),

    cyrus_branch('cyrus-imapd-3.8'),
    cyrus_branch('cyrus-imapd-3.10', [ '/3.10', '/', '/stable' ]),
    cyrus_branch('cyrus-imapd-3.12'),
);

if ($opt->only_dev) {
    %source = { cyrus_branch('master', [ '/' ]) };
}

sub run_or_die ($cmd, @args) {
    say "===> running $cmd @args";
    system $cmd $cmd, @args;
    return if $? == 0;

    if ($? == -1) {
        die "could not execute '$cmd': $!\n";
    } elsif ($? & 127) {
        my $msg = sprintf "'$cmd' died with signal %d, %s coredump\n",
                          ($? & 127),  ($? & 128) ? 'with' : 'without';
        die $msg;
    } else {
        my $msg = sprintf "'$cmd' exited with value %d\n",
                          $? >> 8;
        die $msg;
    }
}

sub run_and_ignore_nonzero ($cmd, @args) {
    say "===> running $cmd @args";
    system $cmd $cmd, @args;
    return if $? == 0;

    if ($? == -1) {
        die "could not execute '$cmd': $!\n";
    } elsif ($? & 127) {
        my $msg = sprintf "'$cmd' died with signal %d, %s coredump\n",
                          ($? & 127),  ($? & 128) ? 'with' : 'without';
        die $msg;
    } else {
        # nonzero exit value, ignore it
        return;
    }
}

# set up PATH
$ENV{PATH} = join(q{:}, qw( /usr/local/bin /usr/bin /bin ));
say qq{#### \$PATH is "$ENV{PATH}"};

# set up our basedir
make_path($basedir);
chdir $basedir or die "chdir $basedir: $!\n";

# pull the target
if (-d $builddir) {
    say "#### we already have a build directory, cool...";
} else {
    say "#### creating a build dir...";
    make_path($builddir);
}

# build the docs from each source
foreach my $source_name (sort keys %source) {
    say "::group::building $source_name section of site"; # GitHub Actions log

    my $details = $source{$source_name};
    my $dir = canonpath("$basedir/$source_name");
    my $branch = $details->{branch} || $source_name;

    my $src;

    if ($details->{is_archive}) {
        $src = canonpath("$workdir/archived-versions/$details->{version}");
        say "#### will use archived version from $src...";
    } else {
        # first make sure we have the source tree
        if (! -d $dir) {
            my $repo_url = $repo{ $details->{repo} };
            say "#### cloning repo for $source_name...";
            run_or_die('git', 'clone', $repo_url,
                       '--branch', $branch,
                       '--single-branch',
                       '--no-tags',
                       $dir);
        } else {
            say "#### updating repo for $source_name...";
            run_or_die('git', '-C', $dir,
                       'fetch', 'origin');
        }

        say "#### building docs for $source_name...";
        run_or_die('git', '-C', $dir,
                   'checkout', '-q', "origin/$branch");
        run_or_die('make', '-C', canonpath("$dir/docsrc"), 'html');

        $src = canonpath("$basedir/$source_name/docsrc/build/html");
    }

    for my $path ($details->{paths}->@*) {
        say "#### rsyncing $source_name docs to $path...";
        my $dst = canonpath("$builddir/$path");

        # n.b. trailing / on src argument is load-bearing
        run_or_die('rsync', '-av', "$src/", $dst);
    }

    say "::endgroup::"; # GitHub Actions log
}

say "#### all done!";

#### SUBS ONLY BELOW

sub archive_copy ($version) {
    return $version => {
        is_archive => 1,
        version    => $version,
        paths      => [ "/$version" ],
    };
}

sub cyrus_branch ($branch, $paths = undef) {
    return (
        $branch => {
            repo   => 'imapd',
            branch => $branch,
            paths  => $paths // [ "/" . ($branch =~ s{^cyrus-imapd-}{}r) ]
        },
    );
}