man caspar (Conventions) - Makefile snippets for common tasks

NAME

caspar - Makefile snippets for common tasks

SYNOPSIS

In a Makefile, do either

include caspar/mk/caspar.mk

include caspar/mk/docbook.mk

include caspar/mk/pod.mk

DESCRIPTION

Caspar offers Makefile snippets for common tasks, like installing configuration files, or typesetting LaTeX, DocBook XML and DocBook SGML documents.

The typesetting functionality is delivered by docbook.mk and pod.mk. This is documented in caspar-typesetting(7).

The installing-stuff functionality functionality is delivered by caspar.mk. (That's what the rest of the manual will talk about.) It enables one to run 'make install' from within a tree which typically holds configuration files, managed using CVS (or Subversion or any other version control system, for that matter).

It is useful in cases like this: all configuration files of some host are under version control, and, after commiting a change to CVS, you want to be able to easily install the new configuration file on the host.

With caspar, all you have to do is specify the hostname in one place, and specify the name of the target directory in each CVS directory.

USAGE

Within a CVS tree, create a file include/install.mk, with contents like e.g.

csp_SUH = root@some.host.somewhere include caspar/mk/caspar.mk

. Within each other directory of the CVS tree which holds files, create a Makefile, which looks like e.g.

csp_SCPDIR = /some/dir/ectory/ include ../../include/install.mk

. If you'd like to use the install-recursive target too, in directories which hold subdirectories (but not files), you'll have to create a Makefile which looks something like

include ../../include/install.mk

. From within the CVS tree, one can call:

make <filename>-install make install make load make make install-recursive

The install-recursive target descends down the tree, and calls make install in each subdirectory.

VARIABLES

The variables one can set in a calling Makefile are:

cp binary, just "cp" by default

extra arguments to pass to cp invocation, none by default

scp binary, just "scp" by default

extra arguments to pass to scp invocation, e.g. '-i .ssh/id_rsa-root'

ssh-reachable user@host (Secure User at Host)

space separated list of ssh-reachable user@host items (Secure User at HostS)

directory to which we can cp(1), instead of scp (CoPy DIRectory)

space separated list of directories to which we can copy (CoPy DIRectorieS)

directory on ssh reachable host, with trailing / (Secure CoPy DIRectory)

this is the list $(csp_SUH):$(dir) for each $(dir) in $(csp_SUHS) (or where dir = $(csp_SCPDIR), in case csp_SUHS is not set). However, more items can get added to this list on the fly.

targets which should depend on the `load' target.

extra files which should be installed. Can be used to include files starting with a dot.

files which should never be installed. Set to Makefile .%.swp %~ #%# pod2htmd.tmp pod2htmi.tmp by default.

extra files which should never be installed; added to list in csp_TABOOFILES.

files which should be installed, even if in initial csp_TABOOFILES list. Removed from csp_TABOOFILES list.

directories to exclude in install-recursive target. set to CVS .svn by default.

see csp_TABOOFILES equivalents.

EXAMPLES

Some examples:

Using csp_CPDIR and csp_LOAD: username/etc/Makefile is

csp_CPDIR = $(HOME)/etc/ csp_LOAD = crontab-load include ../include/install.mk

crontab-load: crontab $(csp_CPDIR)/crontab

while ../include/install.mk is just

include caspar/mk/caspar.mk

. Using csp_SCPDIR and csp_LOAD: etc/Makefile is

csp_SCPDIR = /etc/ csp_LOAD = aliases-load include ../include/install.mk

aliases-load: ssh $(csp_SUH) "cd /etc; postalias aliases; postfix reload"

while ../include/install.mk is

csp_SUH = root@some.host.somewhere include caspar/mk/caspar.mk

Using the csp_TABOOFILES_{ADD,SKIP} variables is handy if you want to install a Makefile, instead of using it: Create Makefile just as you'd like to have it installed on the remote location. Now, create GNUmakefile as e.g.

csp_TABOOFILES_SKIP = Makefile csp_TABOOFILES_ADD = GNUmakefile

csp_SCPDIR = /etc/foobar/ csp_SUH = root@some.host.somewhere

load: ssh $(csp_SUH) "make -C $(csp_SCPDIR)"

Now, make install and make load will do the right thing. Using the csp_EXTRAFILES variable is handy if you want to install files with a leading dot. E.g.:

csp_EXTRAFILES = .bashrc csp_SUHDIRS = root@some.host.somewhere:

More advanced tricks: supply e.g.

csp_SUHS = root@localhost root@some.host.somewhere

in install.mk, to install on multiple hosts. Run

csp_SUH=joe@otherhost make filename-install

to install filename as joe@otherhost, instead of the default as given in install.mk.

When you don't want to ssh to root@some.host.somewhere directly, you could do

sudo rsync -az /path/to/your/config_archive /etc

FILES

caspar/mk/caspar.mk, caspar/mk/docbook.mk, caspar/mk/pod.mk

ENVIRONMENT

For caspar.mk: csp_CPDIR, csp_CP, csp_CPFLAGS, csp_LOAD, csp_SCP, csp_SCPFLAGS, csp_SUH, csp_SUHS, ...

BUGS

See TODO and/or BUGS, distributed with the caspar package. (And online at http://mdcc.cx/pub/caspar/caspar-latest/TODO.)

TRIVIA

caspar is named after Caspar the Friendly Ghost, since that's the title of the Daniel Johnston song I was listening to when deciding to package my homegrown scripts.

AUTHOR

Joost van Baal

cd ~tigrou/pwet.fr/man/linux/Conventions/caspar