head	1.2;
access;
symbols
	tame-0-4:1.2.0.2;
locks; strict;
comment	@# @;


1.2
date	2005.06.17.16.08.40;	author dm;	state Exp;
branches;
next	1.1;

1.1
date	2004.06.13.04.12.07;	author dm;	state Exp;
branches;
next	;


desc
@@


1.2
log
@add quotes for later automake
@
text
@\input texinfo   @@c -*-texinfo-*-
@@c $Id: sfslib.texi,v 1.1 2004/06/13 04:12:07 dm Exp $
@@c %**start of header
@@setfilename sfslib.info
@@c @@include version.texi
@@include dirs.texi
@@settitle SFS @@value{VERSION} Programmers Manual
@@setchapternewpage off

@@iftex
@@alias dslash = slash
@@end iftex

@@ifnottex
@@macro dslash
/
@@end macro
@@end ifnottex

@@macro hslash
/
@@end macro

@@c %**end of header

@@direntry
* SFS libraries: (sfslib).      SFS libraries programmer's guide
@@end direntry

@@ifinfo
This file documents SFS, the self-certifying file system.

Copyright 2004 David Mazi@@`eres

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.
@@end ifinfo

@@c  This title page illustrates only one of the
@@c  two methods of forming a title page.

@@titlepage
@@title SFS @@value{VERSION} Programmer's Manual
@@c @@subtitle SUBTITLE-IF-ANY
@@author David Mazi@@`eres

@@c  The following two commands
@@c  start the copyright page.
@@page
@@vskip 0pt plus 1filll
Copyright @@copyright{} 2004 David Mazi@@`eres

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.
@@end titlepage

@@contents

@@node Top, Setting up, (dir), (dir)
@@comment node-name,     next,           previous, up
@@top SFS

@@ifinfo
This file documents the SFS asynchronous I/O, RPC, and crypto, and
file system contsruction libraries.

This document applies to version @@value{VERSION} of the SFS
distribution.
@@end ifinfo

@@menu
* Setting up::                  Setting up your build directory
* Contacts::                    How to contact people involved with SFS
* Concept Index::               Index of concepts
@@end menu

@@node Setting up, Contacts, Top, Top
@@comment  node-name,  next,  previous,  up
@@chapter Setting up a build directory using the SFS libraries

SFS's build process makes use of the GNU autoconf, automake, and
libtool packages.  Autoconf in particular is what creates the familiar
@@file{./configure} script.  It is highly recommended that you use
these tools to set up the build directory for your project if you are
building against the SFS libraries.

If you set up your project directory properly, your software will by
default search for and link against an installed version of SFS, but
can also be configured via the @@option{--with-sfs=@@var{dir}} flag to
link against an uninstalled SFS build tree.  The latter is quite
useful for debugging, as one can use an unoptimized SFS build that was
compiled with dmalloc.

To set up a new project directory, you must perform the following
steps:

@@enumerate
@@item
Create a new directory for your project, say @@file{yourproject}

@@item
Copy the files @@file{acinclude.m4} and @@file{setup} from an SFS source
distribution into your @@file{yourproject/} directory.

@@item
Create a @@file{configure.in} file in @@file{yourproject/}, including
some SFS-specific boilerplate and any extra tests you need to perform
to determine properties of the compiler and operating system.
@@xref{Minimal configure.in}, for more information on doing this.

@@item
Create a @@file{Makefile.am} file in @@file{yourproject/}, specifying
what programs to build from what source files, and where to install
them.  @@xref{Simple Makefile.am}, for more information on doing this.

@@item
Create files @@file{.cvsignore}, @@file{AUTHORS}, @@file{NEWS},
@@file{README}, by running the following commands in
@@file{yourproject/}:
@@example
touch AUTHORS NEWS README
cat <<EOF > .cvsignore
.deps
.libs
Makefile
Makefile.in
aclocal.m4
config.cache
config.guess
config.h
config.h.in
config.log
config.status
config.sub
configure
install-sh
libtool
ltconfig
ltmain.sh
missing
mkinstalldirs
stamp-h
stamp-h.in
EOF
@@end example

@@item
Now you are ready to build your software, which you can do by running
the following commands in @@file{yourproject/}:
@@example
sh ./setup
./configure --with-sfs=@@var{sfs-build-directory}
gmake
@@end example
@@end enumerate


@@menu
* Software requirements::       Software you must install to build with SFS
* Minimal configure.in::        Example @@file{configure.in} file
* Simple Makefile.am::          Example @@file{Makefile.am} file
* Makefile.am with XDR files::  Example @@file{Makefile.am} RPC @@file{.x} file
@@end menu

@@node Software requirements, Minimal configure.in, Setting up, Setting up
@@comment  node-name,  next,  previous,  up
@@section Software requirements for using autoconf/automake

In order to use @@command{autoconf} and @@command{automake}, you will
need the following software packages installed on your machine.  (Many
operations systems have an easy way of installing software packages,
so you might check your local operating system's packaging system
before installing these from scratch.)

@@table @@strong
@@item dmalloc
@@cindex @@command{dmalloc}
@@command{dmalloc} is a debugging malloc library, available from
@@uref{http:/@@dslash{}dmalloc.com/}.  When developing software with the
SFS libraries, you should link against dmalloc, as this also enables a
number of debugging features in SFS@@.  If you do not develop with
dmalloc, you will severely, severely regret it, unless you are a far
better programmer than the SFS developers.  Far easier to discover
bugs as you create them, with dmalloc, than to go back later and try
to find what is causing improper behavior in thousands of lines of
code you have already written@@enddots{}

@@item GNU m4
@@cindex @@command{m4}
This is the macro processor used by @@command{autoconf}, available from
@@uref{ftp:/@@dslash{}ftp.gnu.org@@dslash{}pub@@dslash{}gnu@@dslash{}m4}.
Non-GNU versions of @@command{m4} often do not work with
@@command{autoconf}.

@@item autoconf
@@cindex @@command{autoconf}
Processes @@file{configure.in} to produce the @@file{configure}
script, available from
@@uref{ftp:/@@dslash{}ftp.gnu.org@@dslash{}pub@@dslash{}gnu@@dslash{}autoconf}.

@@item automake
@@cindex @@command{automake}
Processes @@file{Makefile.am} files to produce the @@file{Makefile.in}
files that @@command{configure} in turn uses to create @@file{Makefile}
files.  Available from
@@uref{ftp:/@@dslash{}ftp.gnu.org@@dslash{}pub@@dslash{}gnu@@dslash{}automake}.

@@item libtool
@@cindex @@command{libtool}
Used by @@command{automake}-generated @@command{Makefile}s to use and
create libraries.  Available from
@@uref{ftp:/@@dslash{}ftp.gnu.org@@dslash{}pub@@dslash{}gnu@@dslash{}libtool}.
@@end table


@@node Minimal configure.in, Simple Makefile.am, Software requirements, Setting up
@@comment  node-name,  next,  previous,  up
@@section Minimal @@file{configure.in} file

@@cindex @@file{configure.in}

@@example
dnl $Id: sfslib.texi,v 1.1 2004/06/13 04:12:07 dm Exp $
dnl
dnl Process this file with autoconf to produce a configure script.
dnl

AC_INIT(acinclude.m4)
AM_INIT_AUTOMAKE(YOUR-PROJECT, 0.0)
AM_CONFIG_HEADER(config.h)

AC_CANONICAL_HOST

dnl Checks for programs.
AC_PROG_CC
AC_PROG_CPP
AC_PROG_CXX
SFS_WFLAGS
AC_C_INLINE
AC_PROG_INSTALL
AC_PROG_LN_S

AM_DISABLE_SHARED

dnl
dnl Deal with incompatibility between certain versions
dnl of autoconf and automake. 
dnl
test -z "$target" && target="$host"

AM_PROG_LIBTOOL

SFS_SFS

dnl ***************************************************
dnl Here is where you should put any tests of your own

dnl
dnl ***************************************************

SFS_CFLAGS

ETAGS_ARGS='-C /dev/null'
AC_SUBST(ETAGS_ARGS)

AC_OUTPUT(Makefile)
@@end example

@@node Simple Makefile.am, Makefile.am with XDR files, Minimal configure.in, Setting up
@@comment  node-name,  next,  previous,  up
@@section Simple @@file{Makefile.am} example

@@cindex @@file{Makefile.am}

@@example
## Process this file with automake to produce Makefile.in
# $Id: sfslib.texi,v 1.1 2004/06/13 04:12:07 dm Exp $

dnl
dnl By default LDEPS is set to all the static libraries you need to
dnl link against.  If the SFS libraries are static, the default will
dnl be:
dnl
dnl LDEPS = $(LIBSFSMISC) $(LIBSVC) $(LIBSFSCRYPT) \
dnl         $(LIBARPC) $(LIBASYNC)
dnl
dnl You don't need to do anything, but if you are linking against a
dnl subset of the SFS libraries, or want to add your own dependencies,
dnl you can override the default value of LDEPS.  (This is for
dnl dependency purposes only, it doesn't change the actual libraries
dnl your programs are linked against.  See LDADD for that.)
dnl
dnl In any event, programs should be made dependent on LDEPS:
dnl
$(PROGRAMS): $(LDEPS)

dnl Now define the programs you want to build.  Use noinst_PROGRAMS
dnl for programs that do not get installed, bin_PROGRAMS for programs
dnl that get installed in /usr/local/bin, sbin_PROGRAMS for ../sbin,
dnl etc.
dnl
noinst_PROGRAMS = yourprogram

dnl For each program, list the source files it includes
dnl
yourprogram_SOURCES = yourprogram.C

dnl If you want to change what all programs link against by default in
dnl this directory, you can set LDADD (either here or in
dnl configure.in).  The default is:
dnl 
dnl LDADD = $(LIBSFSMISC) $(LIBSVC) $(LIBSFSCRYPT) \
dnl         $(LIBARPC) $(LIBASYNC) $(LIBGMP)

dnl If you want to change just what yourprogram links against, for
dnl instance to and library yourlib.la in addition to the libasync
dnl libraries, you can set the following variable:
dnl
dnl yourprogram_LDADD = yourlib.la $(LDADD)


dnl Have to list all headers here, if you want them included with in
dnl output of the "make distcheck" command.  If you want some headers
dnl installed in /usr/local/include, put them in a variable named
dnl include_HEADERS instead of noinst_HEADERS.
dnl
noinst_HEADERS = yourprogram.h

CLEANFILES = core *.core *~

EXTRA_DIST = .cvsignore setup
MAINTAINERCLEANFILES = aclocal.m4 install-sh mkinstalldirs \
        missing configure config.guess config.sub config.h.in \
        ltconfig ltmain.sh INSTALL COPYING Makefile.in stamp-h.in
@@end example

@@node Makefile.am with XDR files,  , Simple Makefile.am, Setting up
@@comment  node-name,  next,  previous,  up
@@section Example of @@file{Makefile.am} file with XDR file

@@example
## Process this file with automake to produce Makefile.in
# $Id: sfslib.texi,v 1.1 2004/06/13 04:12:07 dm Exp $

$(PROGRAMS): $(LDEPS)

noinst_PROGRAMS = yourprogram
yourprogram_SOURCES = yourprogram.C your_prot.C

noinst_HEADERS = yourprogram.h your_prot.x

your_prot.h: $(srcdir)/your_prot.x
        @@@@rm -f $@@@@
        -$(RPCC) -h $(srcdir)/your_prot.x || rm -f $@@@@

your_prot.C: $(srcdir)/your_prot.x
        @@@@rm -f $@@@@
        -$(RPCC) -c $(srcdir)/your_prot.x || rm -f $@@@@

dist-hook:
        cd $(distdir) && rm -f your_prot.h your_prot.C

$(yourprogram_OBJECTS): your_prot.x

CLEANFILES = core *.core *~ your_prot.h your_prot.C

EXTRA_DIST = your_prot.x .cvsignore setup
MAINTAINERCLEANFILES = aclocal.m4 install-sh mkinstalldirs \
        missing configure config.guess config.sub config.h.in \
        ltconfig ltmain.sh INSTALL COPYING Makefile.in stamp-h.in
@@end example

@@node Contacts, Concept Index, Setting up, Top
@@comment  node-name,  next,  previous,  up
@@chapter How to contact people involved with SFS

Please report any bugs you find in SFS to
@@email{sfsbug@@@@redlab.lcs.mit.edu}.

You can send mail to the authors of SFS at
@@email{sfs-dev@@@@pdos.lcs.mit.edu}.

There is also a mailing list of SFS users and developers at
@@email{sfs@@@@sfs.fs.net}.  To subscribe to the list, send mail to
@@email{sfs-subscribe@@@@sfs.fs.net}.


@@page
@@node    Concept Index,  , Contacts, Top
@@comment  node-name,  next,  previous,  up
@@unnumbered Concept Index

@@printindex cp

@@bye

@@c Local Variables:
@@c makeinfo-options: "--no-split --fill-column=70"
@@c End:

@@c  LocalWords:  libtool malloc dmalloc SFS
@


1.1
log
@skeletal internals documentation
@
text
@d2 1
a2 1
@@c $Id$
d5 1
a5 1
@@include version.texi
d252 1
a252 1
dnl $Id$
d306 1
a306 1
# $Id$
d372 1
a372 1
# $Id$
@

