The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
OODoc-2.02
River stage zero No dependents
1 ++
/ oodist

SEE ALSO

This module is part of $project distribution version $version, built on $today.$web

LICENSE

Copyrights $year$author.$contrib

$lictext

__POD_TAIL

   my $pmhead  = eval qq{"$pmheadsrc"};
   error __x"pmhead: {err}", err => $@ if $@;

   my $podtail = eval qq{"\n$podtailsrc"};
   error __x"podtail: {err}", err => $@ if $@;

   ($pmhead, $podtail);
}

sub create_readme($$$) { my ($doc, $readmefn, $workdir) = @_; my @toplevel = glob "$workdir/*";

    my $readme   = first { /\breadme$/i } @toplevel;
    return 1 if $readme;

    info "adding README";

    my $manifest = first { /\bmanifest$/i } @toplevel;
    open MANIFEST, '>>', $manifest
        or fault __x"cannot append to {file}", file => $manifest;
    print MANIFEST "README\n";
    close MANIFEST;

    $readme      = File::Spec->catfile($workdir, 'README');

    if($readmefn)
    {   # user provided README
        info "copying $readmefn as README\n";

        copy $readmefn, $readme
            or fault __x"cannot copy {from} to {to}"
              , from => $readmefn, to => $readme;

        return 1;
    }

    #
    # Produce a README text
    #

    open README, '>', $readme
        or fault __x"cannot write to {file}", file => $readme;

    my $date = localtime;

    print README <<__README;
=== README for $project version $version
=   Generated on $date by OODoc $ooversion

There are various ways to install this module:

 (1) if you have a command-line, you can do:
       perl -MCPAN -e 'install <any package from this distribution>'

 (2) if you use Windows, have a look at http://ppm.activestate.com/

 (3) if you have downloaded this module manually (as root/administrator)
       gzip -d $project-$version.tar.gz
       tar -xf $project-$version.tar
       cd $project-$version
       perl Makefile.PL
       make          # optional
       make test     # optional
       make install

For usage, see the included manual-pages or http://search.cpan.org/dist/$project-$version/

Please report problems to http://rt.cpan.org/Dist/Display.html?Queue=$project

__README

    close README;
    1;
}

# Since ExtUtils::MakeMaker, the META files only get updated when # they already exist. sub create_meta($) { my ($doc) = @_; my $manifest = first { /\bmanifest$/i } glob "*"; $manifest or panic "No manifest";

    foreach my $fn ('META.yml', 'META.json')
    {  next if -f $fn;
       info "adding $fn";
       open META, '>>', $fn and close META;

       open MANIFEST, '>>', $manifest
           or fault __x"cannot append to {file}", file => $manifest;
       print MANIFEST "$fn\n";
       close MANIFEST;
    }
}

# # Create a distribution #

sub create_dist($$) { my ($dest, $makefile) = @_;

    info "* Preparing test";
    system "perl Makefile.PL"
        and fault __x"perl Makefile.PL in {dir} failed", dir => $workdir;

    system "make clean >/dev/null"
        and fault __x"make clean in {dir} failed", dir => $workdir;

    move 'Makefile.old', 'Makefile'
        or fault __x"cannot reinstate Makefile in {dir}", dir => $workdir;

    info "* Running make";
    system "make distdir >/dev/null"
       and fault __x"make in {dir} failed", dir => $workdir;

    if($run_tests)
    {   foreach my $testdir (qw/t tests xt/)
        {   -d $testdir or next;

            info "* Running tests in $testdir";
            system "make test TEST_FILES=$testdir/*.t"
#               and fault __x"make test in {dir} failed", dir => $testdir;
        }
    }
    else
    {   info "* Release testing skipped";
    }

    my $distfile = $makefile->{DISTVNAME}. '.tar.gz';
    info "* Building distribution in $distfile";
    unlink $distfile;

    system "make dist >/dev/null"
        and fault __x"make dist in {dir} failed", dir => $workdir;

    $distfile;
}

sub publish_dist($$) { my ($dest, $distfile) = @_; return if $dest eq $workdir;

    print "Distributed package in $dest/$distfile\n";

    -f $distfile
        or error __x"cannot find produced {file}", file => $distfile;

    -d $dest or mkdir $dest
        or fault __x"cannot create {dir}", dir => $dest;

    move $distfile, $dest
        or fault __x"cannot move {from} to {to}", from => $distfile, to=>$dest;
}

# # RAW #

sub create_raw_dist($$) { my ($dest, $makefile) = @_;

    my $rawname = $makefile->{DISTVNAME}.'-raw';
    my $rawfile = $rawname. '.tar.gz';
    info "* Building raw package $rawfile";
    
    unlink $rawfile;
    
    my %manifests;
    foreach my $man (glob "MANIFEST*")
    {   foreach (read_file $man)
        {  s/\s{3,}.*$//;
           next if m/^#/;
           next unless length;
           chomp;
           $manifests{$_}++;
        }
    }
    
    my @manifests = map { "$rawname/$_" } sort keys %manifests;
    symlink('.', $rawname) || readlink $rawname eq '.'
        or fault __x"cannot create temp symlink {name}", name => $rawname;

    local $" = ' ';
    system "tar czf $rawfile @manifests"
        and fault __x"cannot produce {file} with tar", file => $rawfile;

    unlink $rawname;
    $rawfile;
}

sub publish_raw_dist($$) { my ($dest, $rawfile) = @_; return if $dest eq $html_output;

    -d $dest or mkdir $dest
        or fault __x"cannot create {dir}", dir => $dest;

    print "Raw package to $dest/$rawfile\n";

    move $rawfile, $dest
        or fault __x"cannot move {from} to {to}", from => $rawfile, to => $dest;
}

# # HTMLPKG #

sub create_html_dist($$) { my ($dest, $makefile) = @_;

    my $htmlfile = $makefile->{DISTVNAME}.'-html.tar.gz';
    info "* Building html package $htmlfile";

    unlink $htmlfile;

    local $" = ' ';
    system "tar czf $htmlfile *"
        and fault __x"cannot produce {file} with tar", file => $htmlfile;

    $htmlfile;
}

sub publish_html_dist($$) { my ($dest, $htmlfile) = @_;

    return if $dest eq $html_output;

    -d $dest or mkdir($dest)
        or fault __x"cannot create {dir}", dir => $dest;

    info "* HTML package to $dest/$htmlfile";

    move $htmlfile, $dest
        or fault __x"cannot move {from} to {to}", from => $htmlfile, to=>$dest;
}

# # read_makefile MAKEFILE # Collect values of variable defined in the specified MAKEFILE, which was # produced by "perl Makefile.PL" #

sub read_makefile($) { my $makefile = shift;

    open MAKEFILE, '<', $makefile
       or fault __x"cannot open produced Makefile: {file}", file => $makefile;

    my %makefile;
    while( <MAKEFILE> )
    {   $_ .= <MAKEFILE> while !eof MAKEFILE && s/\\$//; # continuations
        s/\n\t*/ /g;

        $makefile{$1} = $2 if m/^([A-Z_][A-Z\d_]+)\s*\=\s*(.*?)\s*$/;

        if(m/^#\s+([A-Z_][A-Z\d_]+)\s*\=>\s*(.*?)\s*$/)
        {   # important information which ended-up in comments ;(
            my ($key, $v) = ($1, $2);
            $v =~ s/q\[([^\]]*)\]/$1/g;  # remove q[]
            $makefile{$key} = $v;
        }
    }

    close MAKEFILE;
    \%makefile;
}

# # skip_links STRINGS # Split list of package names to avoid #

sub skip_links(@) { my @links = map { defined $_ ? split(/[\, ]/, $_) : () } @_; \@links; }

__END__

NAME

oodist - create perl distributions with OODoc

SYNOPSIS

 cd <src>
 oodist [OPTIONS]
   OPTION:                 DEFAULT:
   --pod   or --nopod        produce pod: yes
   --dist  or --nodist       package distribution: yes
   --html  or --nohtml       produce html: yes if templates
   --raw   or --noraw        produce package with raw files: yes
   --tests or --notests      run tests before packaging: yes

  OPTIONS general:
   --distdir  | -d <dir>     makefile:DISTDIR || $ENV{OODOC_DISTDIR} || <src>
   --extends  | -x <path>    empty
   --project  | -p <string>  makefile:DISTNAME
   --rawdir   | -r <dir>     makefile:RAWDIR  || $ENV{OODOC_RAWDIR} || <src>
   --readme        <file>    constructured
   --workdir  | -w <dir>     /tmp/<DISTVNAME>
   --verbose  | -v           true when specified

  OPTIONS for parsers:
   --skip_links <string>     makefile:SKIP_LINKS

  OPTIONS for POD:
   --email    | -e <email>   makefile:EMAIL
   --firstyear| -y <year>    makefile:FIRST_YEAR
   --license  | -l <string>  makefile:LICENSE || $ENV{OODOC_LICENSE} || 'artistic'
   --pmhead   | -h <file>    makefile:PMHEAD  || 'PMHEAD.txt'  || constructed
   --podtail  | -t <file>    makefile:PODTAIL || 'PODTAIL.txt' || constructed
   --website  | -u <url>     makefile:WEBSITE

  OPTIONS for HTML:
   --html-templates <dir>    makefile:HTML_TEMPLATES || 'html'
   --html-output <dir>       makefile:HTML_OUTPUT    || 'public_html'
   --html-docroot <url>      makefile:HTML_DOCROOT   || '/'
   --html-package <dir>      makefile:HTML_PACKAGE

DESCRIPTION

The oodist script is currently only usable on UNIX in combination with Makefile.PL. It is a smart wrapper around the OODoc module, to avoid start work to produce real POD for modules which use OODoc's POD extensions. HTML is not (yet) supported.

Configuring

All OPTIONS can be specified on the command-line, but you do not want to specify them explicitly each time you produce a new distribution for your product. The options come in two kinds: those which are environment independent and those which are. The first group can be set via the Makefile.PL, the second can be set using environment variables as well.

Example: add to the end of your Makefile.PL

 sub MY::postamble { <<'__POSTAMBLE' }
 FIRST_YEAR   = 2001
 WEBSITE      = http://perl.overmeer.net/oodoc
 EMAIL        = oodoc@overmeer.net
 __POSTAMBLE

Main options

The process is controlled by four main options. All options are by default on.

--pod or --nopod

Produce pod files in the working directory and in the distribution.

--dist or --nodist

Create a distribution, containing all files from the MANIFEST plus produced files. Even with nodist, you will end-up with these archives in the working directory (see --workdir).

--html or --nohtml

Create html manual pages. The --html-templates options must point to an existing directory (defaults to the html/ sub-directory).

--raw or --noraw

Create a package which contains the files which are needed to produce the distribution: the pm files still including the oodoc markup.

General options

The other OPTIONS in detail

--readme <filename>

Copy the specified README file into the distribution, if there is no README yet. The name will be added to the MANIFEST. If the option is not specified, a simple file will be created. If this option is specified, but the filename is empty, then the README will not be produced.

--distdir | -d <dir>

The location where the final file to be distributed is placed, by default in the source directory.

--extends | -x <path>

A colon seperated list of directories which contains "raw oodoc" pm and pod files which are (in some cases) used to provide data for base-classes of this module.

--rawdir | --r <dir>

The location where a raw version of the distribution is made. The normal distribution contains expanded POD and stripped PM files. For that reason, you can not use it a backup for your files. If you have co-workers on the module, you may wish to give them the originals.

--verbose | --v

Shows what happens during the process.

--workdir | -w <dir>

The processing will take place in a seperate directory: the stripped pm's and produced pod files will end-up there.

If not provided, that directory will be named after the project, and located in $ENV{TMPDIR}, which defaults to /tmp. For instance /tmp/OODoc/

Options for parsers

--skip_links <strings>

A blank or comma separated list of packages which will have a manual page, but cannot be loaded under their name. Sub-packages are excluded as well. For instance, XML::LibXML has many manual-pages without a package with the same name.

Options to produce POD

--email | -e <email>

The email address which can be used to contact the authors. Used in the automatic podtail.

--firstyear| -y <string>

The first year that a release for this software was made. Used in the automatic podtail. The specified string can be more complex than a simple year, for instance 1998-2000,2003. The last year will be automatically added like -2006, which results in 1998-2000,2003-2006. When the current year is detected at the end of the string, the year will not be added again.

--license | -l ['gpl'|'artistic'|'as_perl'|filename]

The lisense option is a special case: it can contain either the strings gpl, artistic, or as_perl, or a filename which is used to read the actual license text from. The default is as_perl

--pmhead

Each of the stripped pm files will have content of the file added at the top. Each line will get a comment '# ' marker before it. If not specified, a short notice will be produced automatically.

Implicitly, if a file PMHEAD.txt exists, that will be used. variables found in the text will be filled-in.

--podtail

Normally, a trailing text is automatically produced, based on all kinds of facts. However, you can specify your own file. If exists, the content is read from a file named PODTAIL.txt.

After reading the file, variables will be filled in: scalars like $version, $project, $website etc are to your disposal.

--website | -u <url>

Where the HTML documentation related to this module is publicly visible.

Options to produce HTML

--html-docroot <url> This (usually relative) URL is prepended to all absolute links in the HTML output.
--html-output <dir> The directory where the produced HTML pages are written to.
--html-templates <dir> The directory which contains the templates for HTML pages which are used to construct the html version of the manual-pages. The html2 backend accepts a colon separated list of directories.
--html-package <dir> When specified, the html-output directory will get packaged into a a tar achive in this specified directory.
--html_stylesheet <file> Where to find the stylesheet which should be used to display the produced HTML. A copy of the stylesheet will be made and put in the top-level of the HTML directory.