README

$FreeBSD: ports/Tools/scripts/README,v 1.20 2008/05/06 16:17:01 sat Exp $

ardiff - compare two archives easily
addport - replacement for easy-import
bump_revision.pl - Small script to bump the PORTREVISION variable of ports
which are depending on a port with a changed shared lib
version.
consistency-check - check whether all your ports are installed properly,
what files have changed, and what new files there are.
check-latest-link - search for duplicate LATEST_LINK values and send nag
mails to the responsible maintainers
checkcats.py - verify that master categories in all ports are correct and
report any problems.
checknewvers - checks for availability for a newest version of distfiles on
MASTER_SITES (ftp only).
chkorigin.sh - checks all ports in the tree for a wrong PKGORIGIN.
Run this tool after every repocopy.
close-pr - a slightly hacked version of edit-pr(1) to quickly close PR.
de-pkg-comment - converts pkg-comment to COMMENT (will be obsoleted when
the mass conversion is finished)
distclean - compare md5 sums of distfiles in ports/distfiles with currently
installed ports collection in ports/* and prompt to remove
unmatched entries
explicit_lib_depends.sh - shows the current explicit dependency list of libs
for a given installed port
getpr - downloads a problem report from GNATS and attempts to extract
the patch, shar, uuencoded file from it.
this probably needs to be checked for potential security problems.
gnomedepends - Analyse pkg/PLIST and give an advice as to which GNOME ports
should be listes in {RUN,LIB}_DEPENDS for this port
neededlibs.sh - Extract direct library dependencies from binaries.
plist - automate (mostly, at least) pkg-plist generation
prpatch - just does `patch $1 < pr-patch' (pr-patch is created by getpr)
prdone - checks in the port, attempting to fill out the commit message using
information from the problem report and then takes you into edit-pr
so you don't forget to close the PR.
portsearch - A utility for searching the ports tree. It allows more detailed
search criteria than ``make search key='' and accepts
all perl(1) regular expressions.
resolveportsfromlibs.sh - Prints the name(s) of ports(s) given a library
filename, suitable for direct use in LIB_DEPENDS.
splitpatch.pl - A small script to convert multi-file patches to several
appropriately named single-file patches.
tindex - script used to build INDEXes for supported FreeBSD branches, which
are the source of the 'make fetchindex' INDEXes, and the build
failure reports on ports@FreeBSD.org
update-patches - generates updated patches.

----------------------------------------------------------------------

consistency-check gives output like:

Not on filesystem - jade from jade-1.2.1
Only on filesystem - jadefoo
No package md5 available for lessecho
File nsgmls owned by multiple packages sp-1.3.4,jade-1.2.1
No filesystem md5 available for setuser, but it exists
For sgmlnorm, package md5 312d7b63d591e07629e0da4ae4a0ac07 is DIFFERENT from fs md5 of 19f1f901911b90d8e04c6ea69e1b0541!

change $do_md5 to 0 to not check md5, and $do_fs to 0 to not check for
files above those installed by packages.

----------------------------------------------------------------------

The checkcats.py script verifyes that master categories in all ports are
correct and report any problems. It doesn't require any command-line options.
Please beware that full check takes quite some time.

----------------------------------------------------------------------

getpr, prpatch and prdone are used as so:
% cd /usr/ports/CATEGORY/PORT
% getpr PRNUMBER

them out of the PR>
% prpatch

% prdone PRNUMBER ci
port and edit-pr the problem report so you can close it>

----------------------------------------------------------------------

checksum is a script that allows checking of ports to see if their checksums
match, and if they don't, give a diff against the older version to try and
discover why the checksum didn't match.

----------------------------------------------------------------------

distclean is a script that allows to compare md5 checksums of distfiles in
ports/distfiles with list of all md5 sums listed in "md5" files in the ports
collection. After comparing, utility will prompt to remove distfiles which
doesn't have associated md5 entry (most likely outdated distfiles).

----------------------------------------------------------------------

gnomedepends is a script, which analyses pkg/PLIST and gives an advice as to
which GNOME ports should be listes in {RUN,LIB}_DEPENDS for the port to ensure
correct removal of GNOME shared directories. Usage is simple:
% cd /usr/ports/CATEGORY/PORT
% gnomedepends.py
According to the contents of PLIST the port depends on the following GNOME
port(s):

/usr/ports/audio/gnomeaudio, for directories:
share/gnome/sounds

/usr/ports/sysutils/gnomecontrolcenter, for directories:
share/gnome/apps

/usr/ports/x11/gnomecore, for directories:
share/gnome/apps/Games

/usr/ports/x11/gnomelibs, for directories:
etc/sound/events
etc/sound
share/gnome/games
share/gnome/pixmaps
share/gnome

The example above means that you need to have ${PORTSDIR}/audio/gnomeaudio,
${PORTSDIR}/sysutils/gnomecontrolcenter, ${PORTSDIR}/x11/gnomecore and
${PORTSDIR}/x11/gnomelibs listed in {RUN,LIB}_DEPENDS for this port.
Please be warned, that the this only means that the ports listed by the script
required for correct removal of GNOME shared directories, not for the port
functionality, so actual {RUN,LIB}_DEPENDS may have more entries.

----------------------------------------------------------------------
portsearch - A utility for searching the ports tree.

portsearch is a utility to for searching of the ports tree. It permits
much more detailed searches to be performed than ``make search
key='' by allowing you to specify which field(s) to search. It
also supports all valid perl(1) regular expressions for pattern matching.

portsearch displays matching ports in the same format as ``make search''
and also displays the number of matching ports found.

The following command line options are supported:

-h Prints a multi-line help message and exits

-n name Search for name in the name field

-p path Search for path in the path field

-i info Search for info in the comments field

-m maint Search for maint in the Maintainer field

-x index Search for index in the category field

-b b_deps Search for b_deps in the build-depends field

-r r_deps Search for r_deps in the run-depends field

-d deps Search for deps in the both the build and run dependency
fields. This option behaves differently to the other op-
tions, see the EXAMPLES section

-f file Use the index file file instead of /usr/ports/INDEX

All searches are case-insensitive

See the file README.portsearch for further information.

----------------------------------------------------------------------

The update-patches script looks for files in $WRKSRC (if unset, this defaults
to the work/ subdirectory of the current directory) which have a matching .orig
file. It also looks in $PATCHDIR (if unset, this defaults to the files/
subdirectory of the current directory) for patches that correspond to the first
set. If the changes in an existing patch do not reflect the changes in the
files in $WRKSRC, the script renames the existing patch by adding the suffix
.orig and generates a new patch in its place. If no patch existed, the new one
is created with a name that contains the path and filename of the file being
patched, except that "/" separators and "." characters are replaced by
underscores: for example, a new patch to $WRKSRC/foo/bar.c would be created as
$PATCHDIR/patch-foo_bar_c. If you save a .orig backup of a file, but don't
change the file, update-patches will generate an empty patch.

----------------------------------------------------------------------

NOTE: These scripts need work and are *NOT* safe to use unless you know
what they do. Use at your own risk. Patches would be great, but
it is preferred they pass through the maintainer of each particular
script.

README.patchtool

INTRODUCTION
------------
Patchtool is a tool aimed to simplify common operations with patchfiles. It
was designed using real world's experience with the subject and expected to be
very handy for an active porter.


MODES OF OPERATION
------------------
The tool has the following two basic modes of operation:
o generation/update of patchfiles. In this mode user provides list of working
files for which patchfiles are to be generated and the tool generates or
updates corresponding patches automatically guessing if there is an original
version (.orig file, rcs(1)) or it is a completely new file;

o automatic update of the existing patchfiles. In this mode user provides a
list of patchfiles or directories containing patchfiles and the tool
re-generates specified patches. In this mode the tool tries hard to guess
whether the patchfile in question is already up to date or not and updates
only those patchfiles, which are found to be outdated.

The following options are supported:
-a -- automatically save resulting diff into a patchfile;
-f -- don't ask any question if target patchfile already exists and is to be
replaced;
-u -- run tool in the "update" mode (see above);
-i -- perform requested operation (generate or update) even if the
patchfile seems to be up-to-date based on last modification time of
all files involved.

The tool supports dozen environment variables that can be used to override
default settings. You can find complete list at the top of patchtool.py,
following are the most useful ones:
PT_CVS_ID -- CVS id to be added at the top of each patchfile generated
("FreeBSD");
PT_DIFF_ARGS -- diff(1) args used to generate patchfile ("-du");
PT_DIFF_SUFX -- suffix used to save original version of the file (".orig");


KNOWN BUGS AND LIMITATIONS
--------------------------
o It is assumed that each patchfile contains exactly one diff, so the tool
may remove useful diffs when there are several diffs merged into one
patchfile. Actually I don't think that it is a bug, because Porter's
Handbook clearly demands to follow a "one diff - one patchfile" rule.
Perhaps portlint(1) should be extended to warn about such abuses;

o only '+++' supported as the prefix for the name of target file in the
patchfile. Neither '***' nor 'Index:' are not recognised/supported yet;

o please keep in mind that when you are trying to do automatic update and
some of the patches are for auto-generated/mangled files (e.g. configure
script in the situation when USE_LIBTOOL is used) then you would end up
with some of patchfiles containing bogus hunks;

o by default the tool tries to recognise saved original version on the file
first by probing file with '.orig' suffix added and if it fails then by
probing file with ',v' suffix added. If you use other suffix to save
original version, for example '~', then set PT_DIFF_SUFX environment
variable to match your settings, otherwise the tool will not function
properly.


REPORTING BUGS AND PROPOSING ENHANCEMENTS
-----------------------------------------
The author of the tool is Maxim Sobolev . Any bug
reports, patches, proposals or suggestions are encouraged. You can do it
either contacting author directly at the e-mail above or submitting a FreeBSD
problem report.


EXAMPLES
--------
Following are several sample sessions which show common usage patterns for
this tool.

1. Generation mode (useful when creating new port).
$ cd /somewhere/foo ; make
[compilation blows with error in src/bar/baz.c]
$ cd work/foo-1.0/src/bar
[dig here and there and finally find that the problem in baz.c]
$ cp baz.c baz.c.orig
$ vi baz.c
[fixing it]
$ patchtool baz.c
[reading diff]
$ patchtool -a baz.c
Generating patchfile: patch-src_bar_baz.c...ok
$ cd ../../../../
$ make
[works as expected, wow!]
$ make install clean
$ send-pr
[...]

2. Generation mode when target patchfile already exists (Minor port update).
$ cd /somewhere/foo ; make
[...]
1 out of 4 hunks failed--saving rejects to Makefile.rej
>> Patch patch-aa failed to apply cleanly.
*** Error code 1
$ cd work/foo-1.0
[examining Makefile.rej]
$ vi Makefile
[merging changes by hand]
$ patchtool Makefile
[reading diff]
$ patchtool -a Makefile
Target patchfile "patch-aa" already exists, do you want to replace it? [y/N]: y
Generating patchfile: patch-aa...ok
$ cd ../../
$ make clean
$ make install clean
$ send-pr
[...]

3. "Gross" update mode (Major update, when several existing patches do not apply
cleanly).
$ cd /somewhere/foo
$ vi Makefile
[increase PORTVERSION]
$ make fetch makesum patch
[several patches are failing to apply cleanly]
$ cd work/foo-1.0
[doing merging work, finally all changes are merged]
$ cd ../../ ; make all install
[compile and works like a charm]
$ pwd
/somewhere/foo
$ patchtool -u ./
Updating patchfile: patch-aa
Updating patchfile: patch-as
Updating patchfile: patch-foo.c
Updating patchfile: patch-foo_bar.c
$ make clean
$ send-pr
[...]

README.portsearch

PORTSEARCH(1) FreeBSD General Commands Manual PORTSEARCH(1)

NAME
portsearch - A utility for searching the ports tree.

SYNOPSIS
portsearch [-h] [-n name] [-p path] [-i info] [-m maint] [-x index] [-b
b_deps] [-r r_deps] [-d deps] [-f file]

DESCRIPTION
portsearch is a utility to for searching of the ports tree. It permits
much more detailed searches to be performed than ``make search
key='' by allowing you to specify which field(s) to search. It
also supports all valid perl(1) regular expressions for pattern matching.

portsearch displays matching ports in the same format as ``make search''
and also displays the number of matching ports found.

The following command line options are supported:

-h Prints a multi-line help message and exits

-n name Search for name in the name field

-p path Search for path in the path field

-i info Search for info in the comments field

-m maint Search for maint in the Maintainer field

-x index Search for index in the category field

-b b_deps Search for b_deps in the build-depends field

-r r_deps Search for r_deps in the run-depends field

-d deps Search for deps in the both the build and run dependency
fields. This option behaves differently to the other op-
tions, see the EXAMPLES section

-f file Use the index file file instead of /usr/ports/INDEX

All searches are case-insensitive

/usr/ports/INDEX is not updated everytime a change is made to the ports
tree so in order to get the most accurate results from using portsearch
you should consider rebuilding the index thus:

# cd /usr/ports && make index

FILES
/usr/ports/INDEX The ports master index file

EXAMPLES
Find all ports whose name contains "emacs":

portsearch -n emacs

Restrict the search to only those ports whose name begins with "emacs" by
anchoring the match to the beginning of the name:

portsearch -n ^emacs


Find all the ports in the textproc, print, and www categories that are
maintained by Nik or Jim and have a run-time dependency on the tidy(1)
port:

portsearch -x '(textproc|print|www)' -m '(nik|jim)' -r tidy

Note that the regular expression operators have to be quoted to protect
them from the shell.

The behaviour of the -d deps option is slightly different to the other
search options. If used it makes portsearch search both the build- and
run-dependency fields. If the -b b_deps and/or the -r r_deps are used as
well then they are ignored; the deps pattern is used to search both
fields.

Note that

portsearch -d foobar

is not the same as

portsearch -b foobar -r foobar

Normally all the options are logically ANDed together so in the above ex-
ample a port would need to have both a build and run dependency on
"foobar" to match, whereas the -d option logically ORs the two dependency
fields so that only a single dependency is required for a match. This is
primarily to provide an easy way of generating a list of all the depen-
dencies of a port; handy if the maintainer is making changes and needs to
know which other ports may be affected.

DIAGNOSTICS
portsearch exits 0 on success or 1 if a help message was output.

SEE ALSO
perlre(1), ports(7)

AUTHORS
Mark Ovens

BUGS
The "Index" field would probably be better named "Category" but it has
been left unchanged to be consistent with ``make search''.

perl(1) treats ``-'' as a word boundary so when a dependency field is
wrapped over more than one line a port name may get split like this:

gettext-0.10.35 jpeg-6b libproplist-0.10.1 libungif-
4.1.0 png-1.0.6


FreeBSD 13 June 2000 2

pkg-stash