From ca469803fc3353ea3d45b256657a6513c1bef1c7 Mon Sep 17 00:00:00 2001 From: Björn Persson Date: Fri, 19 Apr 2013 09:02:08 +0200 Subject: Added installation instructions. --- INSTALL | 170 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 INSTALL (limited to 'INSTALL') 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: + + bindir + The directory for programs that can be run from a command prompt. + Default: /bin + + datarootdir + The root of the directory tree for read-only architecture-independent data + files. Default: /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: /include + + libdir + The directory for binary libraries and other architecture-specific files, + used only if no directory project is provided. Default: /lib + + gprdir + The directory for GNAT project files. Default: /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. -- cgit v1.2.3