README

FreeBSD Port Tools

Copyright (c) 2003-2009 Sergei Kolobov. All rights reserved.

INTRODUCTION
============

FreeBSD Port Tools consist of the several small scripts run from
port(1) front-end:
- port commit: commit a port into the FreeBSD Ports SVN Repository
- port create: create a new port from a template
- port diff: generate a diff against a previous version of the port
- port fetch: fetch distfile(s) of a new version of the port
- port getpr: get patch/shar from a PR
- port help: display usage summary for port(1) commands
- port install: install a port
- port submit: submit a PR with new port, or port change/update
- port test: automate testing a new port or a port update
- port upgrade: upgrade a port

FreeBSD Port Tools are available at http://sourceforge.net/projects/porttools/.

I would appreciate any feedback, comments or suggestions for improvement. 
Patches are welcome.  Contact me at <sergei@FreeBSD.org>.

BACKGROUND
==========

I have submitted quite a few port PRs myself, and soon got tired of editing
the default send-pr form to fill in the fields. So I first created my own
custom form which simplified the process a little bit, but still not much.

I also wanted to have consistency in the format of Synopsis and other fields
across all of my PRs.  So I came up with these home-grown tools. I use them for
several months now (approximately since November 2002) and find them quite
useful (at least, for me).  Hopefully, they could be useful for somebody else.

See list of PRs submitted by me as an example what it looks like:
http://www.freebsd.org/cgi/query-pr-summary.cgi?originator=kolobov&closedtoo=on

USAGE
=====
Let us assume you are interested in helping out with one of the ports.
The most convenient way of doing that with the Port Tools is the following.
Even though the Port Tools have 3 most of diff generation, the recommended is 
SVN (default). Do not be scared away at this point - it is very simple.
Let me give a quick overview:

1. Check out a working copy of the port. I usually do it in ~/ports directory:
   (NOTE: my ~/ports directory contains only those ports I am interested in,
   i.e. either maitain or send changes/updates to. Thus, it does not have
   to contain the whole FreeBSD Ports tree)

   sgk@elf:~% cd ~/ports
   sgk@elf:~/ports% svn co ipsvd

   ipsvd is the sample port name.

2. Now, make your changes - e.g. change PORTVERSION from 0.6.0 to 0.6.1.

   sgk@elf:~/ports/ipsvd% cd ipsvd
   sgk@elf:~/ports/ipsvd% vim Makefile

3. At this moment we need to fetch the new distfile and run "make makesum" 
   to update the distinfo file. There is even simpler way to accomplish this 
   with the Port Tools version 0.50 or later:

   sgk@elf:~/ports/ipsvd% port fetch

4. Now we want to make sure that the port compiles, installs and works fine:

   sgk@elf:~/ports/ipsvd% port test

5. Once I am satisfied with the results, let us submit a PR 
   with the port update:

   sgk@elf:~/ports/ipsvd% port submit
   
Now, this was a very simple case, and it did not show off all the features 
of the Port Tools, so please check port(1) manual page for details.
 
THANKS
======
Several people have contributed ideas and/or code to the FreeBSD Port Tools,
see THANKS file for details.

TODO
====
There are some improvements planned, see TODO file for details.

DISCLAIMER
==========

This program is free software; you can redistribute it and/or modify it under
the terms of the 2-clause Simplified BSD License which is distributed with the
software in the file LICENSE.

$Id: README,v 1.9 2009/09/09 19:58:30 skolobov Exp $