diff options
| -rw-r--r-- | INSTALL | 275 |
1 files changed, 275 insertions, 0 deletions
@@ -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. |