Rombobjörn

summaryrefslogtreecommitdiff
path: root/INSTALL
diff options
context:
space:
mode:
Diffstat (limited to 'INSTALL')
-rw-r--r--INSTALL275
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.