mirror of
https://github.com/pgbackrest/pgbackrest.git
synced 2024-12-12 10:04:14 +02:00
f716e98ad0
Docker outputs build info to stderr even when the build is successful. This seems to be especially true on Mac M1. ContainerTest.pm already does this suppression so add it the other places where containers are built.
386 lines
13 KiB
Perl
Executable File
386 lines
13 KiB
Perl
Executable File
#!/usr/bin/perl
|
|
####################################################################################################################################
|
|
# doc.pl - PgBackRest Doc Builder
|
|
####################################################################################################################################
|
|
|
|
####################################################################################################################################
|
|
# Perl includes
|
|
####################################################################################################################################
|
|
use strict;
|
|
use warnings FATAL => qw(all);
|
|
use Carp qw(confess);
|
|
use English '-no_match_vars';
|
|
|
|
$SIG{__DIE__} = sub { Carp::confess @_ };
|
|
|
|
use Cwd qw(abs_path);
|
|
use File::Basename qw(dirname);
|
|
use Getopt::Long qw(GetOptions);
|
|
use Pod::Usage qw(pod2usage);
|
|
use Storable;
|
|
|
|
use lib dirname(abs_path($0)) . '/lib';
|
|
use lib dirname(dirname(abs_path($0))) . '/lib';
|
|
use lib dirname(dirname(abs_path($0))) . '/build/lib';
|
|
use lib dirname(dirname(abs_path($0))) . '/test/lib';
|
|
|
|
use pgBackRestTest::Common::ExecuteTest;
|
|
use pgBackRestTest::Common::Storage;
|
|
use pgBackRestTest::Common::StoragePosix;
|
|
|
|
use pgBackRestDoc::Common::Doc;
|
|
use pgBackRestDoc::Common::DocConfig;
|
|
use pgBackRestDoc::Common::DocManifest;
|
|
use pgBackRestDoc::Common::DocRender;
|
|
use pgBackRestDoc::Common::Exception;
|
|
use pgBackRestDoc::Common::Log;
|
|
use pgBackRestDoc::Common::String;
|
|
use pgBackRestDoc::Html::DocHtmlSite;
|
|
use pgBackRestDoc::Latex::DocLatex;
|
|
use pgBackRestDoc::Markdown::DocMarkdown;
|
|
use pgBackRestDoc::ProjectInfo;
|
|
|
|
####################################################################################################################################
|
|
# Usage
|
|
####################################################################################################################################
|
|
|
|
=head1 NAME
|
|
|
|
doc.pl - Generate pgBackRest documentation
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
doc.pl [options]
|
|
|
|
General Options:
|
|
--help Display usage and exit
|
|
--version Display pgBackRest version
|
|
--quiet Sets log level to ERROR
|
|
--log-level Log level for execution (e.g. ERROR, WARN, INFO, DEBUG)
|
|
--deploy Write exe.cache into resource for persistence
|
|
--no-exe Should commands be executed when building help? (for testing only)
|
|
--no-cache Don't use execution cache
|
|
--cache-only Only use the execution cache - don't attempt to generate it
|
|
--pre Pre-build containers for execute elements marked pre
|
|
--var Override defined variable
|
|
--key-var Override defined variable and use in cache key
|
|
--doc-path Document path to render (manifest.xml should be located here)
|
|
--out Output types (html, pdf, markdown)
|
|
--out-preserve Don't clean output directory
|
|
--require Require only certain sections of the document (to speed testing)
|
|
--include Include source in generation (links will reference website)
|
|
--exclude Exclude source from generation (links will reference website)
|
|
|
|
Variable Options:
|
|
--dev Set 'dev' variable to 'y'
|
|
--debug Set 'debug' variable to 'y'
|
|
=cut
|
|
|
|
####################################################################################################################################
|
|
# Load command line parameters and config (see usage above for details)
|
|
####################################################################################################################################
|
|
my $bHelp = false;
|
|
my $bVersion = false;
|
|
my $bQuiet = false;
|
|
my $strLogLevel = 'info';
|
|
my $bNoExe = false;
|
|
my $bNoCache = false;
|
|
my $bCacheOnly = false;
|
|
my $rhVariableOverride = {};
|
|
my $rhKeyVariableOverride = {};
|
|
my $strDocPath;
|
|
my @stryOutput;
|
|
my $bOutPreserve = false;
|
|
my @stryRequire;
|
|
my @stryInclude;
|
|
my @stryExclude;
|
|
my $bDeploy = false;
|
|
my $bDev = false;
|
|
my $bDebug = false;
|
|
my $bPre = false;
|
|
|
|
GetOptions ('help' => \$bHelp,
|
|
'version' => \$bVersion,
|
|
'quiet' => \$bQuiet,
|
|
'log-level=s' => \$strLogLevel,
|
|
'out=s@' => \@stryOutput,
|
|
'out-preserve' => \$bOutPreserve,
|
|
'require=s@' => \@stryRequire,
|
|
'include=s@' => \@stryInclude,
|
|
'exclude=s@' => \@stryExclude,
|
|
'no-exe', \$bNoExe,
|
|
'deploy', \$bDeploy,
|
|
'no-cache', \$bNoCache,
|
|
'dev', \$bDev,
|
|
'debug', \$bDebug,
|
|
'pre', \$bPre,
|
|
'cache-only', \$bCacheOnly,
|
|
'key-var=s%', $rhKeyVariableOverride,
|
|
'var=s%', $rhVariableOverride,
|
|
'doc-path=s', \$strDocPath)
|
|
or pod2usage(2);
|
|
|
|
####################################################################################################################################
|
|
# Run in eval block to catch errors
|
|
####################################################################################################################################
|
|
eval
|
|
{
|
|
# Display version and exit if requested
|
|
if ($bHelp || $bVersion)
|
|
{
|
|
print PROJECT_NAME . ' ' . PROJECT_VERSION . " Documentation Builder\n";
|
|
|
|
if ($bHelp)
|
|
{
|
|
print "\n";
|
|
pod2usage();
|
|
}
|
|
|
|
exit 0;
|
|
}
|
|
|
|
# Disable cache when no exe
|
|
if ($bNoExe)
|
|
{
|
|
$bNoCache = true;
|
|
}
|
|
|
|
# Make sure options are set correctly for deploy
|
|
if ($bDeploy)
|
|
{
|
|
my $strError = 'cannot be specified for deploy';
|
|
|
|
!$bNoExe
|
|
or confess "--no-exe ${strError}";
|
|
|
|
!@stryRequire
|
|
or confess "--require ${strError}";
|
|
}
|
|
|
|
# one --include must be specified when --required is
|
|
if (@stryRequire && @stryInclude != 1)
|
|
{
|
|
confess "one --include is required when --require is specified";
|
|
}
|
|
|
|
# Set console log level
|
|
if ($bQuiet)
|
|
{
|
|
$strLogLevel = 'error';
|
|
}
|
|
|
|
# If --dev passed then set the dev var to 'y'
|
|
if ($bDev)
|
|
{
|
|
$rhVariableOverride->{'dev'} = 'y';
|
|
}
|
|
|
|
# If --debug passed then set the debug var to 'y'
|
|
if ($bDebug)
|
|
{
|
|
$rhVariableOverride->{'debug'} = 'y';
|
|
}
|
|
|
|
# Doesn't make sense to pass include and exclude
|
|
if (@stryInclude > 0 && @stryExclude > 0)
|
|
{
|
|
confess "cannot specify both --include and --exclude";
|
|
}
|
|
|
|
logLevelSet(undef, uc($strLogLevel), OFF);
|
|
|
|
# Get the base path
|
|
my $strBasePath = abs_path(dirname($0));
|
|
|
|
my $oStorageDoc = new pgBackRestTest::Common::Storage(
|
|
$strBasePath, new pgBackRestTest::Common::StoragePosix({bFileSync => false, bPathSync => false}));
|
|
|
|
if (!defined($strDocPath))
|
|
{
|
|
$strDocPath = $strBasePath;
|
|
}
|
|
|
|
my $strOutputPath = "${strDocPath}/output";
|
|
|
|
# Create the out path if it does not exist
|
|
if (!-e $strOutputPath)
|
|
{
|
|
mkdir($strOutputPath)
|
|
or confess &log(ERROR, "unable to create path ${strOutputPath}");
|
|
}
|
|
|
|
# Merge key variables into the variable list and ensure there are no duplicates
|
|
foreach my $strKey (sort(keys(%{$rhKeyVariableOverride})))
|
|
{
|
|
if (defined($rhVariableOverride->{$strKey}))
|
|
{
|
|
confess &log(ERROR, "'${strKey}' cannot be passed as --var and --key-var");
|
|
}
|
|
|
|
$rhVariableOverride->{$strKey} = $rhKeyVariableOverride->{$strKey};
|
|
}
|
|
|
|
# Load the manifest
|
|
my $oManifest = new pgBackRestDoc::Common::DocManifest(
|
|
$oStorageDoc, \@stryRequire, \@stryInclude, \@stryExclude, $rhKeyVariableOverride, $rhVariableOverride,
|
|
$strDocPath, $bDeploy, $bCacheOnly, $bPre);
|
|
|
|
if (!$bNoCache)
|
|
{
|
|
$oManifest->cacheRead();
|
|
}
|
|
|
|
# If no outputs were given
|
|
if (@stryOutput == 0)
|
|
{
|
|
@stryOutput = $oManifest->renderList();
|
|
|
|
if ($oManifest->isBackRest())
|
|
{
|
|
push(@stryOutput, 'man');
|
|
}
|
|
}
|
|
|
|
# Build host containers
|
|
if (!$bCacheOnly && !$bNoExe)
|
|
{
|
|
foreach my $strSource ($oManifest->sourceList())
|
|
{
|
|
if ((@stryInclude == 0 || grep(/$strSource/, @stryInclude)) && !grep(/$strSource/, @stryExclude))
|
|
{
|
|
&log(INFO, "source $strSource");
|
|
|
|
foreach my $oHostDefine ($oManifest->sourceGet($strSource)->{doc}->nodeList('host-define', false))
|
|
{
|
|
if ($oManifest->evaluateIf($oHostDefine))
|
|
{
|
|
my $strImage = $oManifest->variableReplace($oHostDefine->paramGet('image'));
|
|
my $strFrom = $oManifest->variableReplace($oHostDefine->paramGet('from'));
|
|
my $strDockerfile = "${strOutputPath}/doc-host.dockerfile";
|
|
|
|
&log(INFO, "Build vm '${strImage}' from '${strFrom}'");
|
|
|
|
$oStorageDoc->put(
|
|
$strDockerfile,
|
|
"FROM ${strFrom}\n\n" . trim($oManifest->variableReplace($oHostDefine->valueGet())) . "\n");
|
|
executeTest("docker build -f ${strDockerfile} -t ${strImage} ${strBasePath}", {bSuppressStdErr => true});
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
# Render output
|
|
for my $strOutput (@stryOutput)
|
|
{
|
|
if (!($strOutput eq 'man' && $oManifest->isBackRest()))
|
|
{
|
|
$oManifest->renderGet($strOutput);
|
|
}
|
|
|
|
&log(INFO, "render ${strOutput} output");
|
|
|
|
# Clean contents of out directory
|
|
if (!$bOutPreserve)
|
|
{
|
|
my $strOutputPath = $strOutput eq 'pdf' ? "${strOutputPath}/latex" : "${strOutputPath}/$strOutput";
|
|
|
|
# Clean the current out path if it exists
|
|
if (-e $strOutputPath)
|
|
{
|
|
executeTest("rm -rf ${strOutputPath}/*");
|
|
}
|
|
# Else create the html path
|
|
else
|
|
{
|
|
mkdir($strOutputPath)
|
|
or confess &log(ERROR, "unable to create path ${strOutputPath}");
|
|
}
|
|
}
|
|
|
|
if ($strOutput eq 'markdown')
|
|
{
|
|
my $oMarkdown =
|
|
new pgBackRestDoc::Markdown::DocMarkdown
|
|
(
|
|
$oManifest,
|
|
"${strBasePath}/xml",
|
|
"${strOutputPath}/markdown",
|
|
!$bNoExe
|
|
);
|
|
|
|
$oMarkdown->process();
|
|
}
|
|
elsif ($strOutput eq 'man' && $oManifest->isBackRest())
|
|
{
|
|
# Generate the command-line help
|
|
my $oRender = new pgBackRestDoc::Common::DocRender('text', $oManifest, !$bNoExe);
|
|
my $oDocConfig =
|
|
new pgBackRestDoc::Common::DocConfig(
|
|
new pgBackRestDoc::Common::Doc("${strBasePath}/../src/build/help/help.xml"), $oRender);
|
|
|
|
$oStorageDoc->pathCreate(
|
|
"${strBasePath}/output/man", {strMode => '0770', bIgnoreExists => true, bCreateParent => true});
|
|
$oStorageDoc->put("${strBasePath}/output/man/" . lc(PROJECT_NAME) . '.1.txt', $oDocConfig->manGet($oManifest));
|
|
}
|
|
elsif ($strOutput eq 'html')
|
|
{
|
|
my $oHtmlSite =
|
|
new pgBackRestDoc::Html::DocHtmlSite
|
|
(
|
|
$oManifest,
|
|
"${strBasePath}/xml",
|
|
"${strOutputPath}/html",
|
|
"${strBasePath}/resource/html/default.css",
|
|
defined($oManifest->variableGet('project-favicon')) ?
|
|
"${strBasePath}/resource/html/" . $oManifest->variableGet('project-favicon') : undef,
|
|
defined($oManifest->variableGet('project-logo')) ?
|
|
"${strBasePath}/resource/" . $oManifest->variableGet('project-logo') : undef,
|
|
!$bNoExe
|
|
);
|
|
|
|
$oHtmlSite->process();
|
|
}
|
|
elsif ($strOutput eq 'pdf')
|
|
{
|
|
my $oLatex =
|
|
new pgBackRestDoc::Latex::DocLatex
|
|
(
|
|
$oManifest,
|
|
"${strBasePath}/xml",
|
|
"${strOutputPath}/latex",
|
|
"${strBasePath}/resource/latex/preamble.tex",
|
|
!$bNoExe
|
|
);
|
|
|
|
$oLatex->process();
|
|
}
|
|
}
|
|
|
|
# Cache the manifest (mostly useful for testing rendering changes in the code)
|
|
if (!$bNoCache && !$bCacheOnly)
|
|
{
|
|
$oManifest->cacheWrite();
|
|
}
|
|
|
|
# Exit with success
|
|
exit 0;
|
|
}
|
|
|
|
####################################################################################################################################
|
|
# Check for errors
|
|
####################################################################################################################################
|
|
or do
|
|
{
|
|
# If a backrest exception then return the code
|
|
exit $EVAL_ERROR->code() if (isException(\$EVAL_ERROR));
|
|
|
|
# Else output the unhandled error
|
|
print $EVAL_ERROR;
|
|
exit ERROR_UNHANDLED;
|
|
};
|
|
|
|
# It shouldn't be possible to get here
|
|
&log(ASSERT, 'execution reached invalid location in ' . __FILE__ . ', line ' . __LINE__);
|
|
exit ERROR_ASSERT;
|