====== Magic Makefile for Debian Packages ======

Every now and then one would like to have a Debian package made of her very own software.


This is where the Magic Makefile comes into play.

===== Source =====

Get it from http://repo.fischglas.de or http://www.fischglas.de/software/magicmakefile.

===== Usage =====

====== Magic Makefile (Version 0.99.7, 0.99.9) =====

==== Create a new Project  ====

create a project directory and populate it:

<code>
mkdir myproject
cd myproject
cp /usr/share/magicmakefile/Makefile .
</code>

Inside Makefile, change:

<code>
APPNAME=some-app
VERSION=0.0
</code>

Create ''magic-makefile.inc'':

<code>
UPLOADURL=http://example.com/cgi/repo-insert
DEBIAN_FULL_NAME=John Doe
DEBIAN_EMAIL=John.Doe@example.com
DEBIAN_HOMEPAGE=http://example.com/debian-local/
VERSION_CONTROL_SYSTEM=git
</code>

**Hint**: as of 0.99.7 you may choose between ''git'' and ''svn''.

**Caveat**: Do not use quotes inside ''magic-makefile.inc''.

If you're planning to use Magic Makefile for several projects or site wide 
you may have a ''~/.magic-makefile.inc'' and even a ''/etc/magic-makefile/magic-makefile.inc''.

Create Debian special foo i.e. the ''debian/'' subdirectory.

<code>
make debian-prepkg
</code>

Add a description to ''debian/control''.
See http://www.debian.org/doc/manuals/maint-guide/dreq.en.html 
for details.


==== Project components ==== 

see below

====== Magic Makefile (Version 0.99.5.1) ======

==== Create a new Project  ====

create a project directory and populate it:

<code>
mkdir myproject
cd myproject
cp /usr/share/magicmakefile/Makefile .
</code>

Inside Makefile, change:

<code>
APPNAME=some-app
VERSION=0.0

UPLOADURL=http://example.com/cgi/repo-insert
DEBIAN_FULL_NAME=John Doe
DEBIAN_EMAIL=John.Doe@example.com
DEBIAN_HOMEPAGE=http://example.com/debian-local/
</code>

**Hint**: as of 0.99.5.1 **no quotation** is needed here.

Create Debian special foo i.e. the ''debian/'' subdirectory.

<code>
make debian-prepkg
</code>

Add a description to ''debian/control''.
See http://www.debian.org/doc/manuals/maint-guide/dreq.en.html 
for details.

==== Project components ====

The basic idea behind Magic Makefile is to provide a fixed set of (mostly) 
flat subdirectories whose contents are to go to corresponding system directories.

E.g. the contents of ''ubin'' will go to ''/usr/bin''.

The list of subdirectories:

^ project subdir   ^ system directory      |
| bin              | /bin                  |
| ubin             | /usr/bin              |
| sbin             | /sbin                 |
| usbin            | /usr/sbin             |
| ushare           | /usr/share/$(APPNAME) |
| ulbin            | /usr/local/bin        |
| ulsbin           | /usr/local/sbin       |
| ulib             | /usr/lib              |
| etc/$(APPNAME)   | /etc/$(APPNAME)       |
| etc/$(APPNAME).d | /etc/$(APPNAME).d     |
| etc/init.d       | /etc/init.d           |
| etc/cron.d       | /etc/cron.d           |
| etc/cron.daily   | /etc/cron.daily       |
| etc/cron.hourly  | /etc/cron.hourly      |
| etc/cron.weekly  | /etc/cron.weekly      |
| etc/cron.monthly | /etc/cron.monthly     |

The contents of ''docs/'' are directed to several 
documentation subdirectories:

^ file name ^ system directory          ^ generated file type ^
| *.sgml    | /usr/share/doc/$(APPNAME) | .html man (.1-.8)   |
| *.html    | /usr/share/doc/$(APPNAME) |                     |
| *.1 .. .8 | /usr/share/man1 .. man8   |                     |
| copyright | /usr/share/doc/$(APPNAME) |                     |

It is encouraged that documentation is provided as DocBook/SGML
because all other document formats (like HTML, TXT and man)
might be derived from SGML by Magic Makefile automatically.

You might want to copy this sample ([[ :project:magic-makefile:manual-sgml-sample ]])
to docs/$(APPNAME).sgml .

==== Development Cycle & Updating ====

After you've changed things and want to release the new version of your software,
follow these steps:

  * update the ''VERSION'' inside Makefile
  * update ''debian/changelog'' (see below)
  * run ''make debian-dpkg''
  * if you have a Subversion repository - run ''make commit''      
  * if you have an APT repository set up the way I have - run ''make debian-upload''

==== Hints ====

=== debian/changelog ===

The format of ''debian/changelog'' looks like this (without leading line numbers):

<code>
     1	magicmakefile (0.99.5) unstable; urgency=low
     2	
     3	  * added recommends dh-make, curl
     4	
     5	 -- chris <magicmakefile@citecs.de>  Tue, 18 Dec 2012 08:53:14 +0100
     6	
     7	magicmakefile (0.99.4) unstable; urgency=low
     8	
     9	  * generic support f. manpages
    10	
    11	 -- chris <magicmakefile@citecs.de>  Mon, 29 Oct 2012 20:11:15 +0100
</code>

  * 1 : package-name (version) (stable|unstable|testing); urgency=(low|high)
  * 2 : empty line
  * 3 : two spaces, '*', space, text
  * 4 : empty line
  * 5 : space, two '-', space, your name, space, '<', your email address, '>', TWO spaces, $( date -R )
  * 6 : empty line

There may be multiple subsequent lines like line 3.