Added generic installation instructions.

1 files changed, 275 insertions, 0 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..9f2270b
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,275 @@
+Building and Installing Software Using Comfignat
+================================================
+
+These are generic installation instructions for programs and libraries whose
+build systems are built around Comfignat. Developers are encouraged to edit
+this file and adapt it to their project.
+
+
+Requirements
+------------
+
+These instructions assume a Unix-like system with the GNAT tools and GNU Make.
+The makefiles may not work with other clones and forks of Make. Use GNU Make if
+possible; it is sometimes available as "gmake" on non-GNU systems. 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.
+
+GPRbuild is used by default but Gnatmake can be used instead if the software is
+written in pure Ada. GPRbuild is required for mixed-language software.
+
+
+Basic Installation
+------------------
+
+The simplest way to build and install the software 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
+-------
+
+If there is an automated test suite, then the command to build and run it
+should be "make check". Beyond that no generic instructions for testing can be
+provided.
+
+
+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 directories project, if your system has one and you
+    want to install to the directories it specifies. A directories project is a
+    GNAT project file that defines directory variables for use by other project
+    files. Multiarch support requires a directories project that can refer to
+    different directories depending on the target architecture. A directories
+    project overrides some but not all of the directory variables listed below.
+
+ relocatable_package
+    If relocatable_package is true and no directories project is provided, then
+    the project file that will be installed with the library will be configured
+    with relative pathnames so that the installed directory tree as a whole can
+    be moved to another location in the filesystem without breaking the project
+    file. Default: false
+
+ 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 programs, binary libraries and
+    other architecture-specific files. Default: <prefix>
+
+ bindir
+    The directory for programs that can be run from a command prompt, used only
+    if no directories project is provided. Default: <exec_prefix>/bin
+
+ libexecdir
+    The top-level directory for programs that are intended to be run by other
+    programs rather than by users, used only if no directories project is
+    provided. Default: <exec_prefix>/libexec
+
+ datarootdir
+    The root of the directory tree for read-only architecture-independent data
+    files. Default: <prefix>/share
+
+ datadir
+    The parent of the application-specific directory for idiosyncratic read-
+    only architecture-independent data files for this software. This is usually
+    the same place as datarootdir, but this variable is provided so that you
+    can move these application-specific files without altering the location for
+    GNAT project files, documentation et cetera. Default: <datarootdir>
+
+ sysconfdir
+    The top-level directory for host-specific configuration files.
+    Default: <prefix>/etc
+
+ localstatedir
+    The root of the directory tree for data files that programs modify while
+    they run. Default: <prefix>/var
+
+ statedir
+    The parent of the application-specific directory for idiosyncratic variable
+    data files for this program. Default: <localstatedir>/lib
+
+ cachedir
+    The parent of the application-specific directory for cached data files that
+    the application can regenerate if they are deleted.
+    Default: <localstatedir>/cache
+
+ logdir
+    The top-level directory for log files. Default: <localstatedir>/log
+
+ runtimedir
+    The top-level directory for files that describe the state of the system and
+    that exist only while some subsystem is running, such as process identifier
+    files and transient Unix-domain sockets. Default: /run
+
+ lockdir
+    The top-level directory for lock files that are used to prevent multiple
+    programs from trying to access a device or other resource at the same time.
+    Default: <runtimedir>/lock
+
+ includedir
+    The top-level directory for source files to be used in the compilation of
+    software using libraries, used only if no directories project is provided.
+    Default: <prefix>/include
+
+ libdir
+    The directory for binary libraries to be used by other software, and the
+    top-level directory for other architecture-specific files, used only if no
+    directories project is provided. Default: <exec_prefix>/lib
+
+ gprdir
+    The directory for GNAT project files to be used in the building of software
+    using libraries. If you set this to a directory that GPRbuild and Gnatmake
+    don't search by default, then you will need to add it to the project search
+    path when using this library, for example through the environment variable
+    GPR_PROJECT_PATH. Default: <datarootdir>/gpr
+
+ localedir
+    The root of the directory tree for locale-specific message catalogs.
+    Default: <datarootdir>/locale
+
+ mandir
+    The root of the directory tree for documentation in the Man format.
+    Default: <datarootdir>/man
+
+ infodir
+    The directory for documentation in the Info format.
+    Default: <datarootdir>/info
+
+ miscdocdir
+    The parent of the application-specific directory for miscellaneous
+    documentation files. Default: <datarootdir>/doc
+
+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 used when the project files are
+preprocessed. They are derived from the Make variables above when the makefiles
+invoke Gnatprep. You may need to define them if you run Gnatprep manually.
+The same defaults as above will be used if the symbols are undefined.
+
+ Directories_GPR
+    The filename of the directories project, if any; corresponding to dirgpr.
+
+ Directories_Project
+    The name of the directories project, if any. This is supposed to be the
+    filename without a path or a suffix.
+
+ Prefix
+ Exec_Prefix
+ Bindir
+ Libexecdir
+ Includedir
+ Libdir
+    These correspond to the like-named Make variables.
+
+ Base
+   If Prefix, Exec_Prefix, Bindir, Libexecdir, Includedir and Libdir are
+   relative pathnames, then Base shall be the absolute pathname of the
+   directory that they are relative to. If those variables are absolute
+   pathnames, then Base shall be undefined.
+
+
+Optional Features
+-----------------
+
+There may be options that can be used to enable or disable certain parts of the
+software. This is done by setting certain variables to "true" or "false" on the
+Make or Gnatprep command line.
+
+The developers really should have listed those options here, or deleted this
+section if there are none.
+
+
+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.
+
+ CPPFLAGS
+    A space-separated list of options to be passed to the C preprocessor when
+    compiling C or C++ 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.
+
+ CXXFLAGS
+    A space-separated list of options to be passed to the compiler when
+    compiling C++ code, used only if GNATFLAGS is undefined.
+
+ FFLAGS
+    A space-separated list of options to be passed to the compiler when
+    compiling Fortran code, used only if GNATFLAGS is undefined.
+
+ GNATBINDFLAGS
+    A space-separated list of options to be passed to Gnatbind, used only if
+    GNATFLAGS is undefined and only when binding a program.
+
+ GNATLINKFLAGS
+    A space-separated list of options to be passed to Gnatlink, used only if
+    GNATFLAGS is undefined, only if the builder is Gnatmake, and only when
+    linking a program.
+
+ 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.