view release on metacpan or  search on metacpan

bin/rs  view on Meta::CPAN

when you remove a package, a file is removed if and only if this package
is the most recent owner of it, and if it's not, nothing will happen,
only the entry in the owner recording list will be removed. On the other hand, if
you're removing a package that's indeed the most recent owner of a file,
but this file has multiple owners, then the file will be restored
to the version of the second most recent owner. That's why I said earlier
that the C<--pool> option is used not only when diffing, but also removing
sometimes. Suppose the second most recent owner is C<oid>, then B<rs> will
try to parse the compiled package C<oid.rs> in C<pool>, and restore the file
according to it.

=item tag

C<tag> takes one argument C<oid> and displays a list of files which are
owned by it, followed by the detailed metadata about them in the database
as JSON.

=item which

Takes an absolute path or a path that's relative to the C<root>, display
its entry in the database, useful to find out to which package a file belongs.

=item list

Print a full list of installed packages, sorted from the most recent to the least.

=item crowded

Find out the crowded places, where more than one package likes to reside, that's
useful if you want a file from a specific package, and also to discover
accidental overwrite.

=back

=head1 CONFIGURATION FILES

(Note I intentionally blur the difference between things like a hash and a hash
reference in the following text, since it's easier to type, and also to comprehend
for non-Perl speakers, Perl speakers should always know what I'm talking
about.)

All configuration files are evaluated using Perl's C<do> statement and
a hash is expected as the return value, with the exception
that the L</build> configuration could also return a subroutine.

You don't necessarily have to know Perl to write the configuration files,
you could just write them in JSON with the C<:> separator substituted
as C<< => >>. That being said knowing a bit of Perl surely will help
you use B<rs> to its best potential, and you don't have to be a Perl
expert to write it, so don't be afraid.

See also the released VM image to have a look at some sane configuration
files and get you started.

=over 4

=item profile

This is a configuration file which collects options that you always need
to specifiy. The keys of the hash are option names while the values are,
well, corresponding values. A typical profile looks like:

    {db => '<file>',
     build => '<file>',
     ign => '<file>',
     pool => '<dir>',
     'compile-as' => '<user>',
     'compile-in' => '<dir>',
     root => '<dir>',
     jobs => <number>}

=item build

This file specifies the building instructions, it's only used by the
C<compile> command, the keys are package names while the values are
hashes that detail the instructions on how the build process
should be done. In the following text that explains the build process,
you'll often see I<the value of something>, or I<if something exists>,
it's talking about this hash.

For many packages the build instruction is exactly the same, you could
alias the build instruction of a package to another one by setting it
to the name of the other package.

As previous mentioned, instead of a hash, the C<build> file
could also return a subroutine which will be called with a collection
of the options, you could then return the building instructions differently,
depending on whether you're bootstrapping or not, for an example.

The build process is divided into several steps:

=over 4

=item 1. pre-configure

If C<pre-configure> exists, the value of it should be a string and
B<rs> will try to evaluate it with C<bash>, before running the
C<configure> script.

Usually something like C<autogen.sh> or C<bootstrap> is run in this step.

=item 2. configure

Unless there's a true value in the C<no-configure> slot, B<rs> will
try to run the <configure> script, if it doesn't exist B<rs> will
run C<autoreconf> to make one. A C<--prefix> switch is always passed,
using the value of the C<prefix> option, along with the value of
C<switch> slot, which if exists, should be an array of configure options
that should be passed to the C<configure> script.

B<rs> will pipe the output of C<configure> to the pager C<less>,
since C<configure> usually outputs important information about whether
a package is properly configured, you should briefly scroll over the
outputs, and exit the pager normally using the C<q> key to start C<make>,
after the C<configure> script stopped procuding output, you don't want
to start C<make> before C<configure> finishes.  If you find something
wrong in the C<configure> outputs, you should type C<Ctrl-C> to abort
the compile process.

=item 3. post-configure

bin/rs  view on Meta::CPAN

you don't have to do this before doing installation using B<rs> since B<rs> will automatically
add them and print a helpful reminder if they're missing during the installation
process. Here's some quick usage introduction:

    # CPAN module A::B::C will be installed along with all its dependency.
    $ rs install A::B::C

    # CPAN module A::B::C will be uninstalled along with all its dependency,
    # so that the rs-cpan directory will be completely empty.
    $ rs uninstall A::B::C

    # CPAN module A::B::C will be immediately restored from the binary packages
    # generated during the first install.
    $ rs install A::B::C

Please see my TPF proposal for more information on the current state, plans,
caveats, etc., I will merge it back here once the granting process finishes.

=head2 CPAN COMMANDS

=over 4

=item install

C<install> accepts the name of a CPAN module (A::B::C) as parameter and installs
this module and all its recursive dependency. No installation will be done if this
module is already installed, but the C<direct> flag will always be set
in the database.

=item uninstall

C<uninstall> takes one argument, the name of the module to be uninstalled,
it must be directly installed by you, i.e. not only as a dependency pulled
in, if it's still being referenced by another module no uninstallation
will be done, but the C<direct> flag will still be cleared in the
database, otherwise this module will be removed along with its dependency,
potentially its dependency's dependency, etc.

=item direct

Print a list of modules that're directly installed by you, in comparison to
the C<list> command where every installed module will be printed.

=item orphan

Show which module has become an orphan, i.e. a module that's neither directly
installed by you nor a dependency of another module. For example, if you only
installed one module using B<rs> and later uninstalled it, this module and
all of its recursive dependency will become orphans, they're removed from the
directory into which CPAN modules are installed, but binary packages of them and
their entries in the reference counting database are not deleted, since
it allows instant restoration if you later decide to re-install this module,
or if you are installing a module that shares dependency with this module.

=item adopt

Adopt all the orphans, binary packages of them and their entries in the
reference counting database will all be removed, there will be no sign
that they ever existed once this command finishes. A typical pattern would be:

    # Module A::B::C looks interesting, install it and have a try.
    $ rs install A::B::C

    # Don't want it anymore.
    $ rs uninstall A::B::C

    # There will be absolutely no sign that module A::B::C is ever installed.
    $ rs adopt

=back

The not CPAN specific commands L</tag> L</which> L</list> L</crowded>
are still very useful when using B<rs> as a CPAN client, please see
their description for more information.

=head1 SEE ALSO

A short L<video|https://www.youtube.com/watch?v=QtMcbqtivOU> introduction
to App::rs as CPAN client.

=head1 LICENSE

The package manager B<rs> as well as the RSLinux VM image are released
under GPLv3.

=head1 AUTHOR

Yang Bo <rslovers@yandex.com>

=cut