Installing from tarballs using checkinstall

Chris Lale

feedback.chrislale@coolscience.co.uk

Revision History
Revision 0.01	9 April 2004	Revised by: cl
Initial release.

One day, you will find a piece of software that you really must have. You cannot find a Debian package (.deb file) and the software is only available as a tarball (.tar.gz or .tgz). Installing from a tarball is not difficult, but it takes longer than installing a Debian package. It may also overwrite existing files, and add new ones, without your knowing about it. checkinstall is a program that supervises the compiling and installation of tarball software. It can keep backups of your existing files, and it produces a .deb file that can be used to remove and reinstall the software using standard Debian tools such as dpkg. This article has been tested successfully with checkinstall 1.5.3 in Debian 3.0 (Woody).

Table of Contents

1. Introduction

2. Outline

3. About tarballs

4. About checkinstall

5. Create a working area for checkinstall

5.1. Prepare a Packages directory
5.2. Prepare a Pseudo-debs directory for storing pseudo-deb packages
5.3. Install the ci.sh script.

6. Install checkinstall

6.1. Install checkinstall using apt
6.2. Install checkinstall from a tarball

7. Configure sudo

7.1. About sudo
7.2. Install sudo
7.3. Modify the /etc/sudoers configuration file
7.4. Editing the /etc/sudoers file with visudo
7.5. Check that sudo enables checkinstall to run from a normal user's account.

8. Working directories for new packages

9. Procedure for a typical installation

9.1. Work as a normal user throughout the installation.
9.2. Put the tarball into your working area
9.3. Extract the files from the tarball
9.4. Read the documentation
9.5. Prepare the documentation directory and the package description file
9.6. Make a customised version of the ci.sh script
9.7. Compile the software
9.8. Install the software

10. Example - create a pseudo-deb package for cdrtools

10.1. Get hold of the tarball
10.2. Create directories and extract files from the tarball
10.3. Create the doc-pak directory containing documentation files
10.4. Create the description-pak file that describes the package
10.5. Modify and copy the ci.sh script to ci-cdrtools.sh
10.6. Compile using GNU make
10.7. Use the script to runcheckinstall
10.8. Test your new cdrtools pseudo-deb package

A. Appendix - The ci.sh script

B. Appendix - About this document

B.1. Copyright information
B.2. Latest version
B.3. Bugs, errors and mistakes
B.4. Spelling, punctuation and grammar
B.5. Conventions used in this document

C. Bibliography and references

C.1. Bibliography
C.2. References

1. Introduction

You can do all the work described in this article from the command line. You can either boot straight into console mode, or open a terminal window in an X session. Common terminal emulators are xterm, gnome-terminal (for the gnome desktop) and konsole (for the KDE desktop).

You should invoke all commands as a normal user unless absolutely necessary. If you need superuser permissions, you can use sudo to limit the scope of your commands and, therefore, limit any accidental damage you might do to the system.

It may be a good idea to look at the appendix about this document, particularly the section about the conventions used in this document.

2. Outline

Create a working area for creating and storing checkinstall packages.
Install checkinstall.
Configure sudo so that you can run it as user Root without having to use su to switch user.
How to set up working directories for new packages.
How to install a typical package.
Example of installing a package using checkinstall.

3. About tarballs

A tarball is a file created by the tar archiving utility. It contains one or more archived files. When tar is run by itself, it produces files with a .tar extension. When tar is combined with gzip, for data compression, the resulting file extensions may be .tgz, .tar.gz or .tar.Z.

4. About checkinstall

checkinstall installs a program which has been compiled in the normal way. (Typically, the commands are ./configure and make.) checkinstall takes over the final stage. It will use the command make install or any other command supplied as an argument to checkinstall.

checkinstall keeps track of all the files created or modified by make install( or any similar command). It builds a standard binary package and installs it in your system, giving you the ability to uninstall it with your Debian distribution's standard package management utilities (dpkg, apt etc).

	Debian specific
	checkinstall will create a Slackware, RPM or Debian compatible package. This article describes the use of checkinstall to create Debian packages only.

5. Create a working area for checkinstall

5.1. Prepare a `Packages` directory

Create a directory called /home/username/Packages/. This is where you will put tarballs, their extracted files, compiled code, backup of replaced files and installation scripts.

$ mkdir /home/username/Packages/

The directory tree looks like this.

/home/
 |__ username/
     |__ Packages/

	Check the directory tree
	You can check the directory tree using either ytree or the tree command: `tree` `-L 2 /home/username/Packages/`

5.2. Prepare a `Pseudo-debs` directory for storing pseudo-deb packages

The packages that you produce with checkinstall can be managed with the standard Debian package tools. However, they are not true Debian packages. For example, they do not take account of dependencies. They will work perfectly on your PC, but they may not install properly on someone else's machine. For this reason I call them 'pseudo-debs'. Create a Pseudo-debs directory under /home/username/Packages and keep your finished packages (including checkinstall) in it.

$ cd /home/username/Packages/
$ mkdir Pseudo-debs

The directory tree looks like this:

/home/
 |__ username/
     |__ Packages/
         |__ Pseudo-debs/    # finished pseudo-deb files here

5.3. Install the `ci.sh` script.

The ci.sh script (see the ci.sh script appendix) makes running checkinstall simpler. The script can be pre-configured with the answers to questions that you are normally asked during installation. There are full instructions in the section about a typical installation. Before you use the script, you must configure sudo so that you can run checkinstall as user Root from the script.

Copy and paste the script ci.sh into a text editor. Save it to the /home/username/Packages/ directory and make it executable. You can find the script in the ci.sh appendix.

/home/
 |__ username/
     |__ Packages/
         |__ Pseudo-debs/
         |__ checkinstall/
         |__ ci.sh           # script

6. Install checkinstall

6.1. Install checkinstall using apt

Currently there is no version for stable (Woody), but you can download a Debian package from unstable. You can search for checkinstall at http://www.debian.org/distrib/packages. You may need to use 'pinning'. [1]. If you are installing the Debian package using apt, skip over the next section to configuring sudo.

6.2. Install checkinstall from a tarball

checkinstall will be the first tarball in your working area. Create the subdirectory using the name of the tarball without its version or file-type suffixes. For example, if the tarball is called checkinstall-1.5.3.tgz, create a subdirectory called /home/username/Packages/checkinstall/.

$ cd /home/username/Packages/
$ mkdir checkinstall

You can get the latest version of checkinstall from http://checkinstall.izto.org/ . Download the tarball and place it in /home/username/Packages/checkinstall/.

The directory tree looks like this.

/home/
 |__ username/
     |__ Packages/
         |__ Pseudo-debs/
         |
         |__ checkinstall/
         |   |__ checkinstall-1.5.3.tgz    # tarball
         |
         |__ ci.sh

6.2.1. Extract files from the checkinstall tarball

Change directory to (/home/username/Packages/checkinstall/). Extract the files from the tarball using tar. During extraction, a new directory will automatically be created to hold the files. The directory is called the 'working directory' and will have the same name as the tarball but without the .tgz suffix. It will be called checkinstall-1.5.3.

$ cd checkinstall
$ tar -xzvf checkinstall-1.5.3.tgz 
...
list of files extracted
...

The relevant part of the directory tree looks like this.

/home/
 |__ username/
     |__ Packages/
         |__ Pseudo-debs/
         |
         |__ checkinstall/
         |   |__ checkinstall-1.5.3    # working directory
         |   |   |__ ...               # extracted files
         |   |   |__ ...
         |   |
         |   |__ checkinstall-1.5.3.tgz
         |
         |__ ci.sh

6.2.2. Compile checkinstall

Now compile, or 'make', the checkinstall program. If the make process stops with an error, it is probably because there are some files that make needs but cannot find on your system. Read the messages, install the Debian packages containing the missing files and try again. You can search the contents of Debian distributions for any files that are part of Debian packages at http://www.debian.org/distrib/packages.

	Auto-completion
	Press the <TAB> key after typing the first few letters of the file name. Some, or all, of the remaining letters will appear without any further effort on your part.

$ cd /home/username/Packages/checkinstall-1.5.3/
$ make
... 
list of make messages
...
make[1]: Leaving directory `/home/username/Packages/\
checkinstall/checkinstall-1.5.3/installwatch-0.6.3'
$

6.2.3. Install checkinstall using `make` `install`

You must switch user to Root and run make install. This creates the executable file /usr/local/sbin/checkinstall, and the configuration file /usr/local/lib/checkinstall/checkinstallrc.

	mkdir with the --parents option
	The --parents option makes sure that you do not get an error if the directory you are trying to create already exists. Also, mkdir creates any non-existing directories in the specified path..

$ su
Password: ******* 
# make install
... 
list of make messages
...
# mkdir --parents /usr/local/lib/checkinstall/
# cp checkinstallrc /usr/local/lib/checkinstall/

6.2.4. Run checkinstall on itself

Normally, you run checkinstall at the make install stage. On this occasion checkinstall was not installed so it could not manage the make install process for you. Run it now to create a file called checkinstall_1.5.3-1_i386.deb in /home/username/Packages/checkinstall/checkinstall-1.5.3/.

# checkinstall
checkinstall 1.5.3, 
Copyright 2001 Felipe Eduardo Sanchez Diaz Duran
This software is released under the GNU GPL.
Installing with "make install"...
===================== Installation results ======================
... 
list of make messages
...
==================== Installation successful ====================
... 
list of processing messages
...

	Debian specific
	The following screen shows the result of choosing to install a Debian pseudo-package.

You must configure the package by answering a number of questions. The first question asks which packaging method you want to use - Slackware, RPM or Debian. Select Debian! You can accept the default answers to the rest of the questions. Exit from user Root when the process has finished.

Please choose the packaging method you want to use.
Slackware [S], RPM [R] or Debian [D]? D

This package will be built according to these values: 
0 - Maintainer: [ username@local-host ]
1 - Summary: [ CheckInstall installations tracker, version 1.5.3 ]
2 - Name: [ checkinstall ]
3 - Version: [ 1.5.3 ]
4 - Release: [ 1 ]
5 - License: [ GPL ]
6 - Group: [ checkinstall ]
7 - Architecture: [ i386 ]
8 - Source location: [ checkinstall-1.5.3 ]
9 - Alternate source location: [ ]
Enter a number to change any of them or press ENTER to continue:

Press <ENTER>.

*****************************************
**** Debian package creation selected ***
*****************************************
Building Debian package...OK
Installing Debian package...OK
Erasing temporary files...OK
Writing backup package...OK
Deleting temp dir...OK 
****************************************************************
Done. The new package has been installed and saved to
/home/username/Packages/checkinstall/checkinstall-1.5.3
     /checkinstall_1.5.3-1_i386.deb
You can remove it from your system anytime using: 
dpkg -r checkinstall
****************************************************************
# exit
$

You can now remove or reinstall checkinstall with a single command! First, move the checkinstall pseudo-deb package to the Pseudo-debs directory.

	Long lines of code
	Some of these commands are longer than the page width. I have continued a single command onto another line by escaping the newline with a back slash (\). Split commands like this will execute quite normally. Alternatively, you can delete the back slash and the newline so that the command is all on one line.

mv /home/username/Packages/checkinstall-1.5.3/ \
checkinstall_1.5.3-1_i386.deb \
/home/username/Packages/Psuedo-debs/ \
checkinstall_1.5.3-1_i386.deb

The relevant part of the directory tree looks like this.

/home/
 |__ username/
     |__ Packages/
         |__ Pseudo-debs/
         |   |__ checkinstall_1.5.3-1_i386.deb   # pseudo-deb
         |
         |__ checkinstall/
         |   |__ checkinstall-1.5.3/
         |   |__ checkinstall-1.5.3.tgz
         |
         |__ ci.sh

To remove checkinstall, invoke dpkg --remove checkinstall as user Root. To re-install it invoke dpkg --install /home/username/Packages/Psuedo-debs/checkinstall_1.5.3-1_i386.deb.

7. Configure sudo

7.1. About sudo

To compile a program you normally use the commands ./configure and make in the source directory as a normal user. You then install the compiled software by running the command make install as user Root. sudo saves you from the constant use of su and exit during the installation. You (or a script) just give checkinstall as an argument to the sudo command.

7.2. Install sudo

Check that sudo is installed by checking the sudo package status using dpkg --status sudo as a normal user. Look for 'installed' in the 'status' line.

$ dpkg --status sudo
Package: sudo
Status: install ok installed
$

If sudo is not installed, you can install it using apt-get install sudo as the user Root.

$ su
Password *******
# apt-get install sudo
...
# exit
$

7.3. Modify the `/etc/sudoers` configuration file

sudo's behaviour is governed by the /etc/sudoers file. Here is a simple /etc/sudoers file with entries that enable user 'username' to run checkinstallwith Root permissions.

The comment lines divide it into sections (Host alias specification, User alias specification, Command alias specification and User privilege specification). There are five possible parts to a User privilege specification. They appear in a table with headings which give a brief description of each part.

1  # sudoers file.
2  # This file MUST be edited with the 'visudo' command as root.
3  #
4  # See the man page for details on how to write a sudoers file.
5 
6  # Host alias specification
7  # ========================
8 
9  # User alias specification
10 # ========================
11 User_Alias MAINTAINERS = username
12 
13 # Command alias specification
14 # ========================
15 Cmnd_Alias DEB = /usr/local/sbin/checkinstall
16 
17 # User privilege specification
18 # ============================
19 # Format:
20 #
21 #--------------------------------------------------------------
22 # User_Alias   Host_Alias = (Runas_Alias)  Authent   Cmnd_Alias
23 #                                          -ication
24 # -------------------------------------------------------------
25 # compulsory   run on     = run as which   PASSWD:   compulsory
26 #              which        user (root     (default)
27 #              hosts        by default)    or      
28 #              (PCs)                       NOPASSWD: 
29 #-------------------------------------------------------------- 
30 #
31 root           ALL        =   (ALL)                      ALL
32 MAINTAINERS    ALL        =   (root)       PASSWD:       DEB
33

Line 11 makes ordinary user 'username' a member of a sudo group called MAINTAINERS. Username is a normal user.

Line 15 makes DEB stand for a list of commands. The list has one entry - /usr/local/sbin/checkinstall.

Line 32 must exist in any /etc/sudoers file. It allows user Root to have complete access.

Line 33 allows members of MAINTAINERS (ie username) to run commands in list DEB (ie /usr/local/sbin/checkinstall after supplying username's password.

	More detail about the sudoers file.
	See the sudoers manual for more information. Enter man sudo at the command line.

7.4. Editing the `/etc/sudoers` file with visudo

You should not edit the /etc/sudoers file directly with a text editor. Instead, use the visudo command which runs a text editor for you. It carries out error checking when you have saved the file and exited. Not surprisingly, judging by its name, visudo uses the editor vi or a similar clone. You can make visudo use another editor using update-alternatives, but this is beyond the scope of this article.

visudo starts vi in command mode. You must press The 'i' key or the <INSERT> key to get into write mode. You can get back to command mode by pressing the <ESC> key. All commands start with a colon (:). You only need a few commands (see table).

vi command	Result of issuing the command
:w	Write to file sudoers.tmp, and continue in command mode.
:q	Quit. (Will not quit unless you have saved changes.
:wq	Write to file sudoers, and quit. (sudoers.tmp is then deleted.)
:q!	Quit without saving changes.

You can learn more about vi, at the newbieDoc website. [2]

Add these lines using visudo:

User_Alias: MAINTAINERS = username
Cmnd_Alias: DEB = /usr/local/sbin/checkinstall
User privilege specification: MAINTAINERS ALL = (root) PASSWD: DEB

Now, every time user 'username' runs sudo checkinstall, checkinstall will run with Root permissions (after prompting for username's password).

7.5. Check that sudo enables checkinstall to run from a normal user's account.

You should be logged in as the normal user that you added to the /etc/sudoers file (User_Alias: MAINTAINERS = username). Try running checkinstall --helpfrom a terminal or terminal window. You should get an error message because you cannot run checkinstall without Root permissions. Try running sudo checkinstall --help. This time you will be prompted for your password. When you have supplied your password, checkinstall's help message will be displayed. By default, sudo will not ask you again for your password until 15 minutes have passed.

checkinstall --help
bash: checkinstall: command not found
$ sudo checkinstall --help
Password: *******
checkinstall 1.5.3, 
Copyright 2001 Felipe Eduardo Sanchez Diaz Duran
...
$

8. Working directories for new packages

When you want to install a new piece of software from a tarball, create a new directory (pkgname), under /home/username/Packages/, and place the tarball in it. During installation you will also place a description-pak file, a modified version of ci.sh and a doc-pak directory in the same directory. When you unpack the tarball, tar will create a new directory called the 'source directory', eg /home/username/Packages/pkgname-pkgversion/.

At the end of a successful installation you can safely remove the pkgname-pkgversion directory containing the extracted files. The original tarball pkgname-pkgversion.tar.gz, your customised doc-pak directory, your customised description-pak file and your modified script file ci-pkgname.sh will remain. It will be a simple matter to re-create the pseudo-deb package using just these customised files and directories.

When the ci.sh script has finished the installation,you will be able to delete the source directory (which can be quite large). The ci.sh script will make copies of important files (including backups of your system's original files changes or removed during installation) in /home/username/Packages/pkgname/.

Here is the part of the directory tree showing directories and files for just the package pkgname:

/home/
 |__ username/
     |__ Packages/
         |__ Pseudo-debs/
         |   |
         |   |__pkgname-pkgversion.deb   # pseudo-deb package
         | 
         |__ pkgname/
         |   |__ doc-pak/
         |   |__ pkgname-pkgversion/     # source directory
         |   |__ ci-pkgname.sh
         |   |__ description-pak
         |   |__ pkgname-pkgversion.tar.gz
         |
         |__ pkgname2/                   # other packages
         |__ pkgname3/

At the end of the installation, all pkgname's files are in /home/username/Packages/pkgname/, except for the final pseudo-deb package which is in /home/username/Packages/Pseudo-debs/. The source directory, created during file extraction (pkgname-pkgversion), can then be safely deleted to save disc space. It can easily be re-created from the files in /home/username/Packages/pkgname/.

9. Procedure for a typical installation

9.1. Work as a normal user throughout the installation.

Carry out the whole process as a normal user. sudo will take care of supplying superuser permissions when you need them (see the section on modifying the sudoers configuration file).

9.2. Put the tarball into your working area

Move to the the top of the working area - the /home/username/Packages/ directory. Create a new directory, immediately below the /home/username/Packages directory, to hold the tarball. Use the name of your tarball without the version numbers. For instance, if your tarball is called pkgname-0.03.tar.gz, create a directory for it called pkgname under /home/username/Packages/.

/home/
 |__ username/
     |__ Packages/           
         |__ pkgname/    # tarball goes in here
         |__ ci.sh

Copy the tarball (eg pkgname-pkgversion.tar.gz or pkgname-pkgversion.tgz) to the new pkgname directory.

9.3. Extract the files from the tarball

Move to the directory containing the tarball and extract the files using tar.

$ cd /home/username/Packages/pkgname/
$ tar -xzvf pkgname-pkgversion.tar.gz

tar will create a new directory with the same name as the tarball, but without the .tar.gz or .tgz suffix.

/home/
 |__ username/
     |__ Packages/
         |__ Pseudo-debs
         |       
         |__ pkgname/
         |   |__ pkgname-pkgversion/        # source directory
         |   |__ pkgname-pkgversion.tar.gz  # tarball
         |
         |__ ci.sh

9.4. Read the documentation

Yes! Read the documentation, especially in files with names like README, INSTALL or COMPILE. There are normally two or three steps to compile a tarball package, and one to install it.

Extract files from the tarball as a normal user. (You have already completed this stage.)
Prepare the extracted files for your system using ./configure. (Do this as a normal user.)
Compile from the extracted files using make. (Do this as a normal user too.)
Install the resulting software using. Without checkinstall you do this directly as user Root. make install. With checkinstall you modify ci.sh and let checkinstall to do this for you.)

Check the procedure for this package.

9.5. Prepare the documentation directory and the package description file

Use a text editor to create a file called /home/username/Packages/pkgname/description-pak. It should describe briefly the purpose of the software you are putting into the package. For instance, if you use nano to edit documents:

$ nano /home/username/Packages/pkgname/description-pak

Create a directory called /home/username/Packages/pkgname/doc-pak/. Copy the documentation files you extracted from the tarball into this directory.

$ mkdir --parents /home/username/Packages/pkgname/doc-pak/
$ cp \
   /home/username/Packages/pkgname/pkgname-pkgversion/README \
   /home/username/Packages/pkgname/doc-pak/
$

	Copying many files
	It is much easier to to this using a file manager such as gmc (Gnome), konqueror (KDE) or ytree (console).

/home/
 |__ username/
     |__ Packages/
         |__ Pseudo-debs
         |      
         |__ pkgname/
         |   |__ doc-pak/                 # documentation directory
         |   |__ pkgname-pkgversion/
         |   |__ description-pak          # package description file
         |   |__ pkgname-pkgversion.tar.gz
         |
         |__ ci.sh

9.6. Make a customised version of the `ci.sh` script

Make a copy of the ci.sh script and save it, with a new name (ci-pkgname.sh), in the same directory as your tarball. Use chmod to make sure that it is executable.

$ cp \
   /home/username/Packages/ci.sh \
   /home/username/Packages/pkgname/ci-pkgname.sh
$ chmod u+x /home/username/Packages/pkgname/ci-pkgname.sh

The tree looks like this.

/home/
 |__ username/
     |__ Packages/
         |__ Pseudo-debs
         |        
         |__ pkgname/
         |   |__ doc-pak/      
         |   |__ pkgname-pkgversion/
         |   |__ description-pak    
         |   |__ ci-pkgname.sh              # script file
         |   |__ pkgname-pkgversion.tar.gz
         |
         |__ ci.sh

Modify the ci-pkgname.sh script so that it contains information relevant options for making and installing the new package. The main part of the script is the sudo checkinstall command and its options. The command is all on one line so you must escape each newline character with a back slash ('\'). Do not forget the space before each back slash - it is the space that separates the options. There must not be any spaces either side of an equals sign ('='). The backup option (--bk, --backup='yes') causes your original files (eg in /usr/*) to be backed up in the source directory. The script moves them safely into the directory above after they have been created (in case you later want to delete the source directory).

Here is the command. It is actually a single line because of the escaped newline characters.

	Debian specific
	The --type=debian option causes checkinstall to produce the pseudo-deb package.

9.6.1. The `sudo` `checkinstall` command

1 sudocheckinstall \
2    --type=debian \
3    --maintainer='first-name surname \<your-id@example.net\>' \
4    --pkgname='pkgname' \
5    --pkgversion='n.nn' \
6    --pkgrelease='username-1' \
7    --pkglicense='Copyright 1996-2002 author. \
8 GNU General Public License. See COPYING' \
9    --arch='i386' \
10    --pkgsource='/home/username/Packages/pkgname/ \
11 pkgname-pkgversion.tar.gz' \
12   --pkgaltsource='http://software.example.net/ \
13 pkgname-pkgversion.tar.gz' \
14   --pakdir='/home/username/Packages/Pseudo-debs' \
15   --docdir='/usr/share/doc/' \   --bk \
16   --backup='yes' \
17 make install
18

9.6.2. The `sudo` `checkinstall` options

Here is a brief explanation of the sudo checkinstall command in the script.

sudo checkinstall command - sudo enables checkinstall to run as user Root.
Type of package - leave as Debian!
Package maintainer - this is you.
Package name - derive this from your tarball, omitting version number and tar.gz/tgz suffix.
Package version - derive this from your tarball's version number.
Package release number - use this to identify the package as a home-grown pseudo-deb, eg use your name as part of the release number so that you don not confuse it with a genuine Debian package.
Package license - find this in the documentation extracted from the tarball; refer to the copyright date, the author, the name of the licence type and the name of the relevant file in the documentation (usually called COPYING).
Architecture - leave this as i386 if you are using a standard IBM PC clone.
Package source - the location of the original tarball on your system.
Package, alternative source - the site from which you downloaded the tarball.
Package directory - where the final package ends up; substitute your username and a number so that you can easily identify the package as a home-grown pseudo-deb.
Documentation directory - leave this as /usr/share/doc; it is where all your documentation should be on a Debian system.
Backup - backs up any overwritten files - advisable to keep this!
Toggle backup - must be set to 'yes' for backup to happen.
make install - this is the command that you would use to install manually, passed to checkinstall as arguments eg checkinstall make install, checkinstall make install_packages, checkinstall setup, checkinstall make modules_install, checkinstall install.sh, etc; read the documentation in the tarball.

The directory tree now looks like this:

/home/
 |__ username/
     |__ Packages/
         |__ Pseudo-debs/
         |
         |__ pkgname/
             |__ pkgname-pkgversion/        # the source directory
             |   |... extracted directories ...
             |   |... extracted files ...
             |   
             |__ doc-pak/                   # documentation files
             |   |__ README
             |   |__ RELEASE
             |   |__ INSTALL
             |   |... etc ...
             |   
             |__ pkgname-pkgversion-2.00.3.tar.gz   # the tarball
             |__ ci-pkgname.sh                      # the script
             |__ description-pak            # description file

9.7. Compile the software

If the ./configure stage is necessary, move to the source directory and run the command ./configure as a normal user.

$ ./configure
...
$

Run make, as a normal user, from the same directory.

$ make
...
$

	Errors?
	This is where you are most likely to have a failure. Usually, this means that you do not have the right software on your system. Make will tell you what is missing. If particular packages must be installed, install them with apt, and try again. If particular files are needed, you must identify which package(s) will supply them. You can search the contents of Debian distributions for any files (or just parts of file names) that are part of packages at http://www.uk.debian.org/distrib/packages.

Errors?

This is where you are most likely to have a failure. Usually, this means that you do not have the right software on your system. Make will tell you what is missing. If particular packages must be installed, install them with apt, and try again. If particular files are needed, you must identify which package(s) will supply them. You can search the contents of Debian distributions for any files (or just parts of file names) that are part of packages at http://www.uk.debian.org/distrib/packages.

9.8. Install the software

When make has finished with no errors, run the ci-pkgname.sh script from the source directory. sudo will prompt you for your normal user password.

$ cd /home/chris/Packages/pkgname/pkgname-pkgversion/
$ ../ci-pkgname.sh
Password: *******
checkinstall 1.5.3, 
Copyright 2001 Felipe Eduardo Sanchez Diaz Duran
           This software is released under the GNU GPL.
Installing with "make INS_BASE=/usr/local install"...
==================== Installation results =======================
Copying documentation directory...
        ==> MAKING "install" ON SUBDIRECTORY "SRCROOT/conf"
...
================= Installation successful =======================

There is a bit of tidying up to do. Accept the default answers to the questions.

Some of the files created by the installation are inside the source
directory: ...
Do you want me to list them?  [n]: n
Should I exclude them from the package? (Saying yes is a good idea)  [y]: y

You have a last chance to change some of the values set in the ci-pkgname.sh script.

0 -  Maintainer: [ username <your-id@example.net> ]
1 -  Summary: [ (The first line of
                 /home/username/Packages/pkgname/description-pak 
                 is displayed here.)]
2 -  Name:    [ cdrtools ]
3 -  Version: [ 2.00.3 ]
4 -  Release: [ username-1 ]
5 -  License: [ Copyright 1996-2002 authorname. 
                GNU General Public License. ]
6 -  Group:   [ checkinstall ]
7 -  Architecture: [ i386 ]
8 -  Source location: [ /home/username/Packages/pkgname/
                        pkgname-pkgversion.tar.gz ]
9 -  Alternate source location: [http://software.example.net/
pkgname/pkgname-pkgversion.tar.gz ]
Enter a number to change any of them or press ENTER to continue:

Press <ENTER>.

checkinstall creates the package and saves it in the Pseudo-debs directory. It also installs the package on your system. You can remove the pseudo-deb package from your system and re-install it using dpkg. (There are more details on how to do this in the section on testing a new pseudo-deb package.)

******************************************************************
 Done. The new package has been installed and saved to
 /home/username/Packages/Pseudo-debs/
  pkgname-pkgversion-username-1_i386.deb
 You can remove it from your system anytime using: 
      dpkg -r pkgname
******************************************************************
$

10. Example - create a pseudo-deb package for cdrtools

10.1. Get hold of the tarball

You can download cdrtools from http://www.fokus.fhg.de/research/cc/glone/employees/joerg.schilling/private/cdrecord.html.

	Cannot find URL?
	If this address becomes out of date, search for cdrtools at http://www.freshmeat.net.

10.2. Create directories and extract files from the tarball

Carry out the whole process as a normal user. The ci.sh script invokes sudo to obtain Root permissions at the appropriate place. Create a new directory underneath /home/username/Packages/ called cdrtools . Put a copy the tarball into the new directory and extract it. In this example, the original tarball, /home/username/download/cdrtools-2.00.3.tar.gz, is copied from wherever it is to /home/username/Packages/cdrtools/.

	Auto completion of file or directory names.
	Type the first two or three letters and press the <TAB> key. Some or all of the file or directory name will appear at the insertion point.

$ cd /home/username/Packages
$ mkdir cdrtools
$ cp \
    /path-to-this-tarball/cdrtools-2.00.3.tar.gz \
    /home/username/Packages/cdrtools/
$ cd cdrtools
$ tar -xzvf cdrtools-2.00.3.tar.gz
...
list of extracted files
...
$

The result is a new source directory, cdrtools-2.00.3/ under /home/username/Packages/cdrtools/, containing all the files needed for compiling cdrtools.

/home/
 |__ username/
     |__ Packages/
         |__ Pseudo-debs/
         |
         |__ cdrtools/
             |__ cdrtools-2.00.3/           # the source directory
             |__ cdrtools-2.00.3.tar.gz

10.3. Create the `doc-pak` directory containing documentation files

Read the files ABOUT, COMPILE, INSTALL, README and README.linux in the source directory. The COMPILE file tells you that you can use GNU make.

	GNU make is the version supplied with Debian.
	You can check this using the command `apt-cache` `show make`.

Create the doc-packdirectory /home/username/Packages/cdrtools/doc-pack/ to hold the documentation files.

$ cd /home/username/Packages/cdrtools/
$ mkdir doc-pak

Copy documentation files from the source directory into doc-pak/.

For example, copy the ABOUT file to the doc-pak directory.

cp \
/home/username/Packages/cdrtools/cdrtools-2.00.3/ABOUT \
/home/username/Packages/cdrtools/docpak/

Other files you might also wish to you copy are:

ABOUT
BUILD
COMPILE
COPYING
INSTALL
PORTING
README
README.audio
README.cdplus
README.cdtext
README.compile
README.copy
README.gmake
README.linux
README.linux-shm
README.mkisofs
README.multi
README.verify
START

10.4. Create the `description-pak` file that describes the package

Create the description-pak file. Gather information for the description from ABOUT, README and other files. (checkinstall only displays the first line during the build process, but all lines are added to the final package.) This is how you would do it using the nano text editor.

$ cd /home/username/Packages/cdrtools/
$ touch doc-pak
$ nano doc-pak

This package contains the following software:
cdda2wav (an digital CD audio extraction program), 
cdrecord (a CD recording program), 
mkisofs (an ISO-9660 file system image creator) 
and others. See ABOUT.

<CTRL>+O
File Name to write: doc-pak
<CTRL>+X
$

10.5. Modify and copy the `ci.sh` script to `ci-cdrtools.sh`

Copy the ci.sh script from /home/username/Packages/ to /home/username/Packages/cdrtools/, changing its name to ci-cdrtools.sh. Check that it is executable by its owner.

	Checking permissions.
	Check using `ls` `-l ci-cdrtools.sh`. An 'x' in the fourth position means 'executable by user': `-rwxr--r--` .

$ cp \
   /home/username/Packages/ci.sh \
   /home/username/Packages/cdrtools/ci-cdrtools.sh

The cdrtools part of the directory tree now looks like this:

/home/
 |__ username/
     |__ Packages/
         |__ Pseudo-debs/
         |
         |__ cdrtools/
             |__ cdrtools-2.00.3/
             |__ doc-pak/                # documentation
             |__ cdrtools-2.00.3.tar.gz
             |__ ci-cdrtools.sh          # the script
             |__ description-pak         # description file

Modify ci-cdrtools.sh so that it contains information relevant to the new cdrtools package. The command is all on one line so you must escape each newline character with a back slash ('\'). Do not forget the space before each back slash - it is the space that separates the options. There must be no spaces either side of an equals sign ('='). The backup option (--bk, --backup='yes') causes your original files (eg in /usr/*) to be saved in the source directory eg cdrtools-2.00.3/backup-0123456789-precdrtools.tgz. The script later moves them to /home/username/Packages/cdrtools/.

If you read the documentation (eg README.compile) you will see that the application will be installed in /opt/schily/bin by default. You must either add this path to the default path, or install cdrtools to a directory which is already a default. The second choice is a more sensible one for Debian. The /usr/local/ directory is where other applications, eg X-CD-Roast, will look for cdrtools' programs.

The make install command option for this is INS_BASE=/usr/local, so the final part of the whole command line becomes make INS_BASE=/usr/local install.

sudo checkinstall \
  --type=debian \
  --maintainer='username \<username@example.net\>' \
  --pkgname='cdrtools' \
  --pkgversion='2.00.3' \
  --pkgrelease='username-1' \
  --pkglicense='Copyright 1996-2002 J. Schilling. 
GNU General Public License. See COPYING' \
  --arch='i386' \  --  
  --pkgsource='/home/username/Packages/cdrtools/\
cdrtools-2.00.3.tar.gz' \
  --pkgaltsource='http://sw.example.net/cdrtools-2.00.3.tar.gz'
  --pakdir='/home/username/Packages/Pseudo-debs/' \
  --docdir='/usr/share/doc/' \
  --bk \
  --backup='yes' \
make INS_BASE=/usr/local install

10.6. Compile using GNU make

Move to the source directory and invoke make. (cdrtools does not use the usual ./configure command before make.)

$ cd /home/username/Packages/cdrtools/cdrtools-2.00.3
$ make
    ...
    ==> MAKING "all" ...
    ==> MAKING DIRECTORY ...
    ==> COMPILING ...
    ==> ARCHIVING  ...
    ==> RANDOMIZING ARCHIVE ...
    ...
$

If the process halts, make will tell you which files it cannot find. You can search the contents of Debian distributions for any files that are part of Debian packages at http://www.uk.debian.org/distrib/packages. When you have identified the missing packages, install them with apt and try again.

10.7. Use the script to runcheckinstall

The ci-cdrtools.sh script runs sudo checkinstall, which in turn runs make INS_BASE=/usr/local install as user Root. It will prompt for normal user's password (not Root's password).

	Run the script from one level below its location.
	Make sure that you prefix the command with two dots and a forward slash when you execute it.

$ ../ci-cdrtools.sh
Password: *******
checkinstall 1.5.3, 
Copyright 2001 Felipe Eduardo Sanchez Diaz Duran
           This software is released under the GNU GPL.
Installing with "make INS_BASE=/usr/local install"...
===================== Installation results =======================
Copying documentation directory...
        ==> MAKING "install" ON SUBDIRECTORY "SRCROOT/conf"
...
=================== Installation successful ======================

There is a bit of tidying up to do. Accept the default answers to the questions.

Some of the files created by the installation are inside the 
source directory: ...
Do you want me to list them?  [n]: n
Should I exclude them from the package? 
(Saying yes is a good idea)  [y]: y

You have a last chance to change some of the values set in the ci-cdrtools script.

0 -  Maintainer: [ first-name surname <your-id@example.net> ]
1 -  Summary: [ This package contains cdda2wav (an digital CD 
audio extraction program), cdrecord (a CD recording program), 
mkisofs (an ISO-9660 filesystem image creator) and others.
See ABOUT.
2 -  Name:    [ cdrtools ]
3 -  Version: [ 2.00.3 ]
4 -  Release: [ surname-1 ]
5 -  License: [ Copyright 1996-2002 J. Schilling. 
                GNU General Public License. ]
6 -  Group:   [ checkinstall ]
7 -  Architecture: [ i386 ]
8 -  Source location: [ /home/username/Packages/cdrtools/
                        cdrtools-2.00.3.tar.gz ]
9 -  Alternate source location: [http://software.freshmeat.net/redir/
cdrecord/35795/url_tgz/cdrtools-2.00.3.tar.gz ]
Enter a number to change any of them or press ENTER to continue:

checkinstall creates the cdrtools.deb package and saves it in the /home/username/Packages/Pseudo-debs/ directory. It also installs cdrtools onto your system.

******************************************************************
 Done. The new package has been installed and saved to
 /home/username/Packages/Pseudo-debs/
 cdrtools_2.00.3-username-1_i386.deb
 You can remove it from your system anytime using: 
      dpkg -r cdrtools
******************************************************************
$

10.8. Test your new cdrtools pseudo-deb package

Here are some things you might want to try. You must be user Root (the superuser) to remove or install the package.

Display package status details.

$ dpkg --status cdrtools

Display available version details

$ dpkg --print-avail cdrtools

List files `owned' by the package.

$ dpkg --listfiles cdrtools

Remove the package. (You must su to user Root.)

# dpkg --remove cdrtools

Reinstall the package. You must use the full filename, including the appropriate path. (You must su to user Root.)

# dpkg --install \
   /home/username/Packages/Pseudo-debs/ \
cdrtools_2.00.3-username-1_i386.deb

Even more things you might want to try.

You can find more options in the manual (man dpkg) or by using the help command (dpkg --help).

A. Appendix - The ci.sh script

Copy and paste this script into a text editor. Save as /home/username/Packages/ci.sh, and make it executable. (See the section on installing the ci.sh script.) You can then make a modified copy of the script for each new installation (see the section on customising the ci-sh script).

#!/bin/bash
#    ci.sh
#    version 0.01
#
#    copyright (c) 2004, Chris Lale <chrislale@coolscience.co.uk>
#
#    This program is free software; you can redistribute it and/or
#    modify it under the terms of the GNU General Public License 
#    as published by the Free Software Foundation.
#
#    This program is distributed in the hope that it will be 
#    useful' but WITHOUT ANY WARRANTY; without even the implied 
#    warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
#    PURPOSE. See the GNU General Public License for more details.
#
#    You should have received a copy of the GNU General Public License
#    along with this program; if not, write to the Free Software
#    Foundation, Inc., 59 Temple Place, Suite 330, Boston, 
#    MA  02111-1307  USA
#
#    http://www.gnu.org/copyleft/gpl.html
#
#    On Debian systems, you can find the complete text of the GNU 
#    General Public License may be found in 
#
#    /usr/share/common-licenses/GPL.
#
#
# About this script
# -----------------
# This script uses sudo to run checkinstall on a Debian system. 
# Checkinstall is used to install software compiled from a tarball.
# It creates a .deb package file and installs it, keeping track of 
# files added to your system, and making a backup of your 
# system's original files. This script runs checkinstall and 
# passes options to it. 
#
# Before running this script
# --------------------------
# You must extract the files from the tarball, and place this 
# script in the directory immediately above the extracted files 
# (ie the same directory as the tarball itself). You must make 
# sure that this script file is executable (chmod u+x ci.sh). You
# must also configure sudo so that a particular normal user may 
# run checkinstall as the superuser.
#
# How to use this script
# ----------------------
# You must edit the options to suit your installation. You may 
# also need to edit the 'make install' statement if the software 
# you are installing uses a variation on this command. The script
# assumes that the description-pak file and the doc-pak directory
# needed by checkinstall are in the same directory as this script
# file.
#
# Place a suitably modified version of this script in the
# directory containing the working directory. Run the script, as 
# a normal user, from the working directory. The working 
# directory will be immediately below the script. Move to the 
# working directory and execute '../ci.sh' without the quotes.
#
# Detailed instructions
# ---------------------
# You can find detailed guide in the article called 'Installing 
# from tarballs using checkinstall' at 
#
#     http://newbiedoc.sourceforge.net.
#
#------------------- script starts here -------------------------
#
# Copy the description file description-pak and document directory
# doc-pak into the top of the build directory. If doc-pak or 
# description-pak exist in the build directory, remove them first.
#
if [ -f description-pak ]; then rm --force description-pak; fi
cp ../description-pak ./
if [ -d doc-pak ]; then rm --force --recursive doc-pak; fi
cp --recursive ../doc-pak ./
#
#----------------- not edit above this line ---------------------
#
# Use sudo to run checkinstall as the superuser. Change these 
# options to suit the tarball's particular COMPILE and INSTALL 
# needs.
#
sudo checkinstall \
     --type=debian \
     --maintainer='first-name surname \<your-id@example.net\>' \
     --pkgname='package-name' \
     --pkgversion='n.nn' \
     --pkgrelease='username-1' \
     --pkglicense='Copyright 1996-2002 author. GNU General Public \
License. See COPYING' \
     --arch='i386' \
     --pkgsource='/home/username/Packages/package-name/\
package-name-version.num.tar.gz' \
     --pkgaltsource='http://software.example.net/\
package-name-version.num.tar.gz' \
     --pakdir='/home/username/Packages/Pseudo-debs/' \
     --docdir='/usr/share/doc/' \
     --bk \
     --backup='yes' \
make install
#
#------------------- Do not edit below this line -----------------
# move backup file(s) to a safe location (the directory above the
# source directory). This allows the source directory to be deleted 
# safely.
#
if ! [ -f backup-* ]; 
then 
        echo Original files were not backed-up.; 
        echo ;
else
        echo Moving backup file one level up from ;
        pwd;
        echo ;
        mv ./backup-* ../;
fi
# Invalidate the user's timestamp by setting the time on it to the
# epoch. The next time sudo is run, a password will be required. 
# This makes accidental use of any permitted commands less likely.
#
sudo -k

B. Appendix - About this document

B.1. Copyright information

Copyright �2004 Chris Lale <feedback.chrislale@coolscience.co.uk>. Permission is granted to copy, distribute and/or modify this document with no Invariant Sections, with no Front-Cover texts and with no Back-Cover Texts under the terms of the GNU Free Documentation License, version 1.1 or any later version, published by the Free Software Foundation. A copy of the license can be found at http://www.fsf.org/copyleft/fdl.html.

if before text, indicates text has been omitted in front of the text
if after text, indicates that following text has been omitted.
if on one line by themselves indicates that lines have been omitted.

my-file.txt
my-directory
/my-path/my-directory/
my-application
my-package
This is some terminal text.

Filenames, application names, package names and text displayed in an X window look like this.

my-file.txt
my-application
my-package
This is some text in an X window.

B.5.5. Commands

Commands issued from a terminal look like this. Use of the <Enter> key is implied but not shown.

$ my command

The 3rd line in this example shows a command issued in X.

Menu bar
   File
      Close

C. Bibliography and references

C.1. Bibliography

apt: man 8 apt - Advanced Package Tool.
apt-cache: man 8 apt-cache - APT package handling utility -- cache manipulator
apt-get: man 8 apt-get - APT package handling utility -- command-line interface.
checkinstall website: http://checkinstall.izto.org/ .
chmod: man 1 chmod - change file access permissions.
dpkg: man 8 dpkg - a medium-level package manager for Debian.
gzip: man 1 gzip - gzip, gunzip, zcat - compress or expand files
less: man 1 less - view a file in a terminal with up and down scrolling.
linux dictionary: - http://www.tldp.org/LDP/Linux-Dictionary/html/index.html - online dictionary of Linux terminology.
make manual: man 1L make - GNU make utility to maintain groups of programs.
mkdir manual: man 1 mkdir - make directories.
nano: man 1 nano - Nano's ANOther editor, and simple to use.
shell scripts: http://gd.tuwien.ac.at/linuxcommand.org/learning_the_shell.html#contents - one of many bash guides on the web.
sudo manual: man 8 sudo - execute a command as another user.
sudo website: http://www.sudo.ws/sudo/.
sudo README: /usr/share/doc/sudo/README - general information about sudo including its philosophy.
sudo OPTIONS: /usr/share/doc/sudo/OPTIONS - who sudo is configured for Debian systems.
sudoers file manual: man 5 sudoers - a list of which users may execute what.
tar: man 1 tar - The GNU version of the tar archiving utility.
tree: man 1 tree - list contents of directories in a tree-like format.
vi: man 1 vi - text editor.
vim: http://newbiedoc.sourceforge.net/text_editing/vim.html - how to use vim - an alternative to vi.
visudo: man 8 visudo - edit the sudoers file.
ytree: man 1L ytree -- file manager for the console.

C.2. References

1. Silva, Gustavo Noronha.: ”apt HOWTO” - managing packages. http://www.debian.org/doc/manuals/apt-howto/ch-apt-get.en.html.
2. Lerallut, Romain.: "VI - Visual Editor"- a quick intro to the basics of the vi editor. http://newbiedoc.sourceforge.net/text_editing/vi.html