Tue, 19 Dec 2006

Writing man pages

On a Debian system, install the following using apt-get:

    asciidoc
    xmlto

Write your man page using asciidoc.  The asciidoc homepage can be found at:

    http://www.methods.co.nz/asciidoc/

where you can also find a user manual which will show examples
on usage.

When writing your man page, start by usng the ascii.1.txt page in 
/usr/share/doc/asciidoc as an example.  Copy this file to your
working area and edit it appropriately.  Once your page is written, 
run the following command:

    asciidoc -v --doctype=manpage --backend=docbook  photon.1.txt

This produces a photon.1.xml file.  Next run this command:

    xmlto man photon.1.xml

This produces a photon.1 man page.

Check photon.1 for small corrections.  It seems to add in extra .sp tags.

Preview your new man page by running this command:

    man ./photon.1

Posted at: 14:10 | category: /dev | Comments ()

Sat, 25 Nov 2006

patch and diff

To create a patch against the most current development version when using SVN:

    svn diff > /path/to/patchfile.diff

For an individual file within SVN:

    svn diff changedfilename > /path/to/patchfile.diff

To create a patch when you are not using SVN:

    diff -Naur oldfile newfile > /path/to/patchfile.diff

    Note also the option -x to exclude files ... for example

        -x '*.po'     can be added to exclude all .po files

To apply a patch:

    patch --verbose [-p0] < /path/to/patchfile.diff

    where -p0 represents how much of the leading path will be dropped off
        -p0 = nothing is removed from the path
        -p1 = the leading '/' will be removed => path/to/patchfile.diff
        -p2 => to/patchfile.diff
        -p3 => patchfile.diff

More info can be found in the patch and diff man pages.  Note that there is a
section at the botton of the patch man that specifically discusses patch
creation.

Posted at: 12:53 | category: /dev | Comments ()

Fri, 11 Aug 2006

Subversion: new project/repository configuration and some basic commands

As root:
    svn mkdir /var/svn/repo/newproject
    chown -R myUser:svnusers /var/svn/repo/newproject
    (presumes you have a svnusers group)

As a user/owner (myUser) of the newproject:
    svnadmin create /var/svn/repo/newproject

As root:
    chown -R myUser:svnusers /var/svn/repo/newproject
    chmod 664 /var/svn/repo/newproject/db/*

As a user/owner (myUser) of the newproject:
    cd /tmp
    mkdir -p newproject/trunk
    mkdir -p newproject/branches
    mkdir -p newproject/tags

    cd /tmp/newproject/trunk
    cp -pvr /home/newproject/www .

    svn import /tmp/newproject file:///var/svn/repo/newproject -m "initial import"

    cd /tmp
    rm -rf newproject/

To verify results of the import:

    svn list --verbose file:///var/svn/repo/newproject

To export the project without .svn files

    cd [to target export directory]
    svn export file:///var/svn/repo/newproject/trunk/www [option name]

To checkout the project with .svn files

    cd [to target working copy directory]
    svn checkout file:///var/svn/repo/newproject/trunk/www [option name]

svn status [file:///var/svn/repo/newproject]
    prints the status of working copy files and directories

svn diff
    shows changes to the working copy

svn update [file:///var/svn/repo/newproject]
    brings changes from the repository to your working copy
        A == added
        D == deleted
        U == updated
        C == conflict
        G == merged

svn add PATH
    adds files/directories to your working copy and schedules them for
    addition to the repository.  will be uploaded and added to the repository
    during the next commit.  when adding a directory, the default behavior is
    to recurse

svn delete PATH
    schedules PATH for deletion on the next commit.  if PATH is a URL, it will
    immediately delete and a log message must be supplied.  

svn copy SRC DST
    copy a file/directory in your working copy or repository.

svn move SRC DST
    move a file/directory in your working copy or repository.  equivalent to
    svn copy/svn delete.  

    example:  svn move foo.c bar.c

svn commit [--message] [PATH]
    sends changes from working copy to the repository.  alias == ci.

    example:  svn commit -F message foo.c
        this only commits the foo.c file and a message

    svn commit without any args will commit everything

svn log [PATH]
    display all of the commit messages

Posted at: 01:27 | category: /dev | Comments ()

qmake - compiling

To compile a C++ application you need to create a makefile. The easiest way to
create a makefile is to use the qmake build tool supplied with Qt. If you've
saved main.cpp in its own directory, all you have to do is: 

qmake -project -o main.pro      // this creates a project file main.pro

qmake                           // this creates the Makefile

make                            // this creates the executable

The first command tells qmake to create a .pro (project) file. The second
command tells it to create a (platform-specific) makefile based on the project
file. You should now be able to type make (or nmake if you're using Visual
Studio).

Posted at: 01:27 | category: /dev | Comments ()

Important pbuilder commands

sudo pbuilder create --distribution sarge
sudo pbuilder update --override-config --distribution sid

pdebuild
   // run this in the directory with source files (above debian/)
   // it builds a deb in /var/cache/pbuilder/results

note that presently pbuilder (sid) uses gcc-4.0 and g++-4.0, which may not be
appropriate for your package.

sudo pbuilder clean

------

piuparts - to check for proper dependencies and whether package install
properly in unstable after completing the build process

cd to the source build directory (above debian/)

    piuparts ../bbmail-0.8.3_i386.deb

------

Building the final package:

// check which complier is default

cd to the source build directory (above debian/)

    dpkg-buildpackage -rfakeroot -k8CE11941

Posted at: 01:27 | category: /dev | Comments ()

Upgrade a Debian Package with new source using svn-upgrade


download a copy of the new source tarball and place it in /debian-dev/tarballs

cd /debian-dev/calcurse  (just above /debian.  this is the WC [working copy])

svn-upgrade ../tarballs/calcurse-1.2.tar.gz

You'll now have a copy of calcurse in /debian-dev/calcurse that is updated to
the latest source.

You can check changes with

    svn diff

or specific files with

    svn diff TODO

Check the status of the svn repository for calcurse with

    svn status

Go ahead and make changes to things like the debian/changelog file.  Once
you've made all your changes you can commit the changes to the svn repository
with 

    svn commit

You can also do this by specific file

    svn commit src/util.c

Once everything is committed, you can build the package with

    svn-buildpackage -k8CE11941 -rfakeroot

which is executed in the WC (just above /debian).

The packages that are built will show up in /debian-dev/build-area.  You
should linda and lintian check them.

You should also run pbuilder on the WC.  Start this process by executing

    sudo pbuilder update
    sudo pbuilder clean

Then, from the WC, run

    pdebuild

You can then go to /var/cache/pbuilder/results to linda/lintian check the
files that were created by pdebuild.

Once you are satisfied that everything is o.k. and have tested it by
installing, upgrading, etc, then from the WC, run 

    svn-buildpackage -k8CE11941 -rfakeroot --svn-tag
or
    svn-buildpackage -k8CE11941 -rfakeroot --svn-tag-only

This will prepare for the next source release by making an entry in
debian/changelog.

Send the following files to the uploader:

    calcurse_1.2-1.diff.gz
    calcurse_1.2-1.dsc
    calcurse_1.2-1_i386.changes
    calcurse_1.2.orig.tar.gz

That's it.

Posted at: 01:27 | category: /dev | Comments ()

Working with svn-buildpackage

Start by creating a svn repository.  I'm presuming you'll be working from your
home directory --

    svnadmin create svn-repo 
    
... where svn-repo can be any name you want.

Note that this repository [svn-repo or whatever you name it] will be where 
svn manages all of its work.  It is not an area that you will edit.

Next, create a directory where you will do your work.   For me it was --

    mkdir debian-dev
    cd debian-dev

Download the appropriate files:  package.dsc, package.orig.tar.gz, and
package.diff.gz

Now we'll inject an existing source file into the repository --

    svn-inject bbtime_0.1.5-9.dsc file:///home/kevin/svn-repo

You'll see a lot of stuff scroll by, the last line of which should say
something like 

"Your working directory is /home/kevin/debian-dev/bbtime - have fun!"

The svn-inject command actually makes your working directory for you.

For most purposes you'll want to work out of the directory, although you can
create other working directories if you like with the command --

    svn co file:///home/kevin/svn-repo/bbtime

Wherever you execute this command is where the working directory will be
built.  When it is built, you'll see the following tree built:

    bbtime
      |----- branches
      |----- tags
      |----- trunk

You'll want to descend into trunk, where you'll see all of the source files
and a debian/ directory with all of the rules/control files.  Later, when you
execute the svn-buildpackage command, you'll want to do so from this trunk
directory. 

Return back to /home/kevin/debian-dev (or your equivalent).  Make a directory
in here as follows --

    mkdir tarballs
    
... so you should now have:

    home/kevin/debian-dev
        |------------------- bbtime
        |------------------- tarballs

Into the tarballs directory copy the original source tarballs, which should
have a name like bbtime_0.1.5.orig.tar.gz.  You should have been able to
download a copy of this file from the same place you downloaded the .dsc file
(most likely the Package area on Debian.org).

At this point you are ready to do some work.   Remember that svn-inject did
the original checking out of the bbtime working files for you, so you can
simply go to them and start your editing --

    cd /home/kevin/debian-dev/bbtime

... and do your work, most of which will probably be in the debian/ directory.

Once you've done your editing, you'll need to execute various svn commands,
all of which should be executed from the working directory, which is
/home/kevin/debian-dev/bbtime.  Examples of some of these commands:

    svn add debian/newfile
    svn delete debian/oldfile
    svn status
    svn log
    svn diff
    svn commit

This last command - svn commit - must be executed before you can do any
building.  As you execute it, you'll be given a chance to write notes about
the changes you made.

The next step is the actual building.  The command is --

    svn-buildpackage -k8CE11941 -rfakeroot

where -k is your GnuPG key ID and -r sets up fakeroot, which you should have
installed.  

You'll see plenty of screen action, which should end with a few lines that
tell you where everything was built.  If you move up a level in the directory,
you'll now find a new sub-directory called build-area.  This is where all of
the built files are put.  So you should now have a tree like this:

    home/kevin/debian-dev
        |------------------- bbtime
        |--------------------build-area
        |------------------- tarballs

In the build-area you'll find all of your newly generated files:

    bbtime_0.8.3-3.diff.gz
    bbtime_0.8.3-3.dsc
    bbtime_0.8.3-3_i386.changes
    bbtime_0.8.3-3_i386.deb
    bbtime_0.8.3.orig.tar.gz

Obviously you'll want to test everything, including running lintian and linda.

You'll probably want to build a few times as you work out your bugs.  Each
time you change something in bbtime/debian, you'll have to svn commit it to
the repository before you can execute svn-buildpackage again.  And each time
you build, svn-buildpackage will automatically overwrite the files in the
build-area directory, so don't worrying about cleaning that out.

When you are finally happy with your results, you need to tag it as a final
build.  You can do this with one of two commands --

    svn-buildpackage -k8CE11941 -rfakeroot --svn-tag
    or
    svn-buildpackage -k8CE11941 -rfakeroot --svn-tag-only

The first command will build the package and tag it, while the latter command
will just tag it (presumes your earlier builds were satisfactory).

When you tag it, you'll also be making a new debian/changelog entry, which
essentially is preparation for the next time you rebuild the package and
release a new version.

At this point you are basically done.  Make sure you don't delete the working
copy of your package that you have in /home/kevin/debian-dev.  Leave it there
for future versions. 

Before ending this, here's a couple more things to think about that may hang
you up.

First, let's say you've just finished building, are happy with the package,
and you've tagged it, which puts a copy into the repository trunk.  You
send it to your upload sponsor, but he spots a bug and wants you to correct
it.  But you've already finalized and tagged your build.  No problem.  Go to
your working copy - /home/kevin/debian-dev/bbtime - and execute the command --

    svn update

This will refresh your working copy from the repository.  It probably already
is the latest copy, but just in case, update it anyway.  Next go into
debian/changelog and remove the next version entry that the tagging process
created for you.  Make any other bug corrections.  And then execute your svn
commit and then you can build again and eventually tag it.  Your versioning
will still be preserved.

The second hang up that may get you is if you checkout a copy of a package
into a different working area.  Say for instance that you are in /tmp and you
execute --

    svn co file:///home/kevin/svn-repo/bbtime

This will create the following tree for you:

    /tmp/bbtime
        |------- branches
        |------- tags
        |------- trunk

You can descend into trunk, where you'll find all the source files and the
debian/ directory.  You can do all the editing you need and commit all of the
changes back to the repository.  And you can even build a deb by executing the
svn-buildpackage command from the trunk/ directory.  It will create a
build-area directory for like this:

    /tmp/bbtime
        |------- branches
        |------- build-area
        |------- tags
        |------- trunk

... and in this build-area directory you'll find the results of your build.
What you won't find is a .diff.gz file.  That file is only generated if you
are working from the originally created working directory from when you
executed svn-inject.

If you, or someone else, works on a copy of the package checked out from the
repository to a working area not in the original /home/kevin/debian-dev and
commits changes, then make sure next time you work in the original work area -
/home/kevin/debian-dev/bbtime - that you execute svn update to incorporate
their changes into your working copy.   This is basic svn stuff but may be
helpful to those new to all of this.

Good luck!

Posted at: 01:27 | category: /dev | Comments ()

ezcounter.php -- counter for webpages



The above page should be added to the target webpage via an include.  
The include needs to be before any echo/print statements as headers 
cannot be sent twice.
Print out the counter value later on the page  with:

Posted at: 01:27 | category: /dev | Comments ()