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 almost all 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: bindir The directory for programs that can be run from a command prompt, used only if no directories project is provided. Default: /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: /libexec datarootdir The root of the directory tree for read-only architecture-independent data files. Default: /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: sysconfdir The top-level directory for host-specific configuration files. Default: /etc localstatedir The root of the directory tree for data files that programs modify while they run. Default: /var statedir The parent of the application-specific directory for idiosyncratic variable data files for this software. Default: /lib cachedir The parent of the application-specific directory for cached data files that the application can regenerate if they are deleted. Default: /cache logdir The top-level directory for log files. Default: /log 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: /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: /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: /gpr localedir The root of the directory tree for locale-specific message catalogs. Default: /locale mandir The root of the directory tree for documentation in the Man format. Default: /man infodir The directory for documentation in the Info format. Default: /info miscdocdir The parent of the application-specific directory for miscellaneous documentation files. Default: /doc 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: /lock 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 Datarootdir Datadir Sysconfdir Localstatedir Statedir Cachedir Logdir Includedir Libdir GPRdir Localedir Mandir Infodir Miscdocdir Runtimedir Lockdir These correspond to the like-named Make variables. 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 and only when linking a program. 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.