Added installation instructions.

2 files changed, 172 insertions, 0 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..a3e57a6
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,170 @@
+Building and Installing the Ada Milter API
+==========================================
+
+Requirements
+------------
+
+These instructions assume a Unix-like system with the GNAT tools and GNU Make.
+The makefiles may not work with other Make clones than GNU Make. If you can't
+use Make you will need to manually preprocess some GNAT project files with
+Gnatprep. If you have another Ada compiler than GNAT, then the included build
+system will probably not work and you should do whatever that compiler requires
+you to do to compile the code.
+
+The project files require GPRbuild. Gnatmake won't do because this is a mixed-
+language project.
+
+
+Basic Installation
+------------------
+
+The simplest way to build and install the Ada Milter API is:
+
+ 1: Go to the directory that contains this file and the makefiles, and run
+    "make" to build the library.
+
+ 2: Run "make install" to copy the files to the default locations. You will
+    probably need root privileges if you install to the default locations.
+    
+
+Testing
+-------
+
+"make test_milter" will build a test milter that can be used to check that the 
+library works. The testing is not automated. A Mail Transfer Agent will need to
+be configured to use the test milter, and some email messages will need to be 
+sent through that MTA.
+
+
+Installation Directories
+------------------------
+
+By default the files are installed in directories under /usr/local. You can
+specify other locations by setting variables on the Make command line, or on
+the Gnatprep command line if you can't use Make. The following Make variables
+are relevant during the build:
+
+ dirgpr
+    The filename of the directory project, if your system has one and you want
+    to install to the directories it specifies. A directory project is a GNAT
+    project file that defines directory variables for use by other project
+    files. Multilib support requires a directory project that can refer to
+    different directories depending on the target architecture. A directory
+    project overrides some but not all of the directory variables listed below.
+
+ prefix
+    A prefix used in the default values of the directory variables listed
+    below. Default: /usr/local
+
+ exec_prefix
+    A prefix used in the default locations for architecture-specific files.
+    Default: <prefix>
+
+ bindir   
+    The directory for programs that can be run from a command prompt. 
+    Default: <exec_prefix>/bin
+    
+ datarootdir
+    The root of the directory tree for read-only architecture-independent data
+    files. Default: <prefix>/share
+
+ includedir
+    The directory for source files that are needed for compilation of code that
+    uses the library, used only if no directory project is provided.
+    Default: <prefix>/include
+
+ libdir
+    The directory for binary libraries and other architecture-specific files,
+    used only if no directory project is provided. Default: <exec_prefix>/lib
+
+ gprdir
+    The directory for GNAT project files. Default: <datarootdir>/gpr
+
+If you want to install to a staging directory from which the files will later
+be copied to their final locations, then set DESTDIR to the staging directory.
+All the other directory variables shall be the final locations. Unlike the
+variables listed above, DESTDIR is effective in the installation step.
+
+The following preprocessor symbols are defined by the makefiles, and may be
+defined manually if Make can't be used:
+
+ Directory_GPR
+    The filename of the directory project, if any; corresponding to dirgpr.
+
+ Directory_Project
+    The name of the directory project, if any. This is supposed to be the
+    filename without a path or a suffix.
+
+ Prefix
+ Exec_Prefix
+ Bindir
+ Includedir
+ Libdir
+    These correspond to the like-named Make variables.
+
+
+Optional Thread Wrapper    
+-----------------------
+
+The Ada Milter API contains a thread wrapper. It wraps threads that Libmilter
+starts, and registers and unregisters them in the Ada run-time system. This may
+be necessary on some platforms and works around a memory leak in some versions
+of Libgnat, but can also trigger bugs in some older versions of Libgnat. The 
+thread wrapper is disabled by default. To enable it, set the variable 
+wrap_threads to "true" on the Make or Gnatprep command line.    
+    
+    
+Build Tools and Options
+-----------------------
+
+The following variables, which may be set in the environment or on the Make
+command line, control which programs are invoked to do the build and which
+options are passed to them:
+
+ GNATPREP
+    The command for invoking Gnatprep, in case you want to use a nondefault
+    version of Gnatprep or a wrapper for example. Default: gnatprep
+
+ GNAT_BUILDER
+    The command for invoking the builder, that is GPRbuild. Default: gprbuild
+
+ GNATFLAGS
+    A space-separated list with all of the optional parameters to be passed to
+    the builder, including any options to be forwarded to the compiler, binder
+    and linker. If GNATFLAGS is defined it overrides the options variables
+    listed below.
+
+ GNAT_BUILDER_FLAGS
+    A space-separated list of options for the builder, used only if GNATFLAGS
+    is undefined. This may include not only options for the builder itself but
+    also command line separators (also called mode switches) followed by
+    options to be forwarded to the compiler, binder or linker.
+
+ ADAFLAGS
+    A space-separated list of options to be passed to the compiler when
+    compiling Ada code, used only if GNATFLAGS is undefined.
+
+ CFLAGS
+    A space-separated list of options to be passed to the compiler when
+    compiling C code, used only if GNATFLAGS is undefined.
+
+ LDFLAGS
+    A space-separated list of options to be passed to the linker, used only if
+    GNATFLAGS is undefined. (Unfortunately GPRbuild can't forward command line 
+    options to the linker when linking a shared library, so LDFLAGS affects 
+    only the test milter.)
+
+
+Copyright of This File
+----------------------
+
+Copyright 2013 B. Persson, Bjorn@Rombobeorn.se
+
+This material is provided as is, with absolutely no warranty expressed
+or implied. Any use is at your own risk.
+
+Permission is hereby granted to use or copy this documentation file
+for any purpose, provided the above notices are retained on all copies.
+Permission to modify the text and to distribute modified text is granted,
+provided the above notices are retained, and a notice that the text was
+modified is included with the above copyright notice.
diff --git a/README b/README
index c285b32..6fcebea 100644
--- a/README
+++ b/README
@@ -19,6 +19,8 @@ Documentation
    specification. In addition to those you should probably read the Libmilter
    documentation, which is available at Milter.org and is also included with
    Sendmail.
+   
+   See the file INSTALL for build and installation instructions.
 
 License