"Fossies" - the Fresh Open Source Software Archive

Member "s-nail-14.9.11/INSTALL" (8 Aug 2018, 13340 Bytes) of package /linux/misc/s-nail-14.9.11.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "INSTALL": 14.9.10_vs_14.9.11.

    1 I n s t a l l i n g  S - n a i l / S - m a i l x
    2 ================================================
    3 
    4 1.0 Compilation
    5 1.1 What if configuration fails?
    6 1.2 What if building fails?
    7 1.3 What if tests fail?
    8 1.4 How can i enable debugging?
    9 2.0 Notes on building the latest release
   10 
   11 1.0 Compilation
   12 ---------------
   13 
   14 System specific notes can be found in the next section.
   15 All (optional) features are documented (and adjustable) in make.rc.
   16 Adjustments may also take place, and are usually done, from the command
   17 line, overriding those made in make.rc (if any).
   18 
   19 Without any adjustments all non-experimental features will be enabled,
   20 except some which provide redundant functionality (e.g., OPT_SPAM_SPAMC
   21 is disabled because the generic OPT_SPAM_FILTER can do the same).
   22 None of the features are "require"d by default, so that configuration
   23 will not fail shall any of them not be available or usable.
   24 The generated configuration is tracked: changes will be recognized
   25 and cause automatic cleanups and rebuilds as necessary.
   26 Experts could find it valuable to adjust some settings in config.h.
   27 
   28   $ make tangerine  # equals "$ make config build test install"
   29   $ make citron     # equals "$ make config build install"
   30   $ make distclean  # *Completely* cleanup working directory
   31 
   32 With adjustments:
   33 
   34   $ make OPT_POP3=no OPT_SMTP=require tangerine
   35   $ make OPT_CROSS_BUILD=y VAL_PREFIX=/some/nasty/prefix citron
   36 
   37 With utility program and feature adjustments:
   38 
   39   $ make awk=/usr/bin/nawk OPT_SOCKETS=no DESTDIR=./zzz tangerine
   40 
   41 If OPT_DOTLOCK has been enabled then the minimal privilege-separated
   42 SETUID (to VAL_PRIVSEP_USER, default "root") helper program will be build
   43 and installed, and therefore the installation process needs to have the
   44 appropriate privileges.  In this case it may be useful to separate the
   45 configuration / building and the installation tasks and give the last
   46 step higher privileges via super(1), sudo(1), su(1) or a similar
   47 mechanism, e.g.:
   48 
   49   $ make VAL_PREFIX=/usr config && make MAKEJOBS='-j 4' &&
   50     super make DESTDIR=./xy install
   51 
   52 would create a "s-nail" binary and install a "s-nail" manual etc.  under
   53 the prefix "/usr" but rooted under "[./]xy", i.e., the binary would be
   54 installed as "[./]xy/usr/bin/s-nail".
   55 Out-of-tree compilation is supported; to use it, create the target
   56 directory of desire, change into it and run the make-emerge.sh script
   57 shipped with S-nail, then proceed as with normal in-tree building.
   58 The following make(1) targets exist, the default being `build':
   59 
   60 - tangerine   Shorthand for "$ make config build test install": create
   61               or check and update configuration, build, test and install.
   62               The variable $DESTDIR will be honoured (see make.rc),
   63               but not be tracked in the configuration.
   64               In order to parallelize the `build' step pass a $MAKEJOBS
   65               variable, as shown below.
   66 - citron      Shorthand for "$ make config build install".
   67               `build' parallelization via $MAKEJOBS, as shown below.
   68 - all         Shorthand for "$ make config build".
   69               `build' parallelization via $MAKEJOBS, as shown below.
   70 
   71 - config      Only create or check and update the configuration.
   72 - build       Only build (using the existing configuration).
   73               This can be parallelized, either by a corresponding make(1)
   74               invocation when the target is run by itself, or by setting
   75               the $MAKEJOBS variable otherwise, e.g., "MAKEJOBS='-j 4'".
   76               $MAKEJOBS is not tracked in the configuration.
   77 - install     Only install using the built files of the existing
   78               configuration.
   79               The variable $DESTDIR will be honoured (see make.rc),
   80               but not be tracked in the configuration.
   81 
   82               S-nail will create an uninstall shell script
   83               (VAL_UAGENT-uninstall.sh), but which will *not* be installed
   84               if $DESTDIR is set non-empty -- within $DESTDIR, that is.
   85               Copy or move it manually from the S-nail root directory ./
   86               into $DESTDIR as necessary.
   87 
   88 - clean       Remove anything which can be rebuild.
   89 - distclean   Remove anything which can be rebuild or reconfigured.
   90 
   91 - test        Run cc-test.sh in --check-only mode on the built binary.
   92 
   93 Setting the make(1) variable $VERBOSE to an arbitrary value during
   94 `config' time, as in "$ make VERBOSE=xy tangerine", will change the
   95 output of the `all', `install' etc. targets to a more verbose one.
   96 
   97 If some libraries are missing that you know are installed on your
   98 system, or if other errors occur due to missing files but which you know
   99 exist, please ensure that the environment variable $C_INCLUDE_PATH
  100 includes the necessary "include/" paths and the environment variable
  101 $LD_LIBRARY_PATH includes the necessary "lib/"rary paths.
  102 
  103 The S-nail make system will inspect these two environment variables and
  104 automatically convert them to cc(1) (c99(1)) -I and -L options (since
  105 these environment variables are, different to the command line options,
  106 not part of the POSIX standard).
  107 To set these environment variables, the following can be done in
  108 a Bourne / Korn / POSIX compatible shell:
  109 
  110   $ C_INCLUDE_PATH="${C_INCLUDE_PATH}:/usr/local/include"
  111   $ LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib"
  112   $ export C_INCLUDE_PATH LD_LIBRARY_PATH
  113   $ make tangerine
  114 
  115 Other than the standard paths /usr/{bin,include,lib} and /usr/local/[.]
  116 should possibly be placed first instead, presuming that they are meant
  117 to override things which usually exist in standard locations.
  118 If all else fails you can also forcefully pass in include directives and
  119 library paths via prefilled $INCS and $LIBS variables:
  120 
  121   $ make INCS=-I/mypath/include LIBS="-L/mypath/lib -lmylib" tangerine
  122 
  123 There are also some predefined configuration sets available, meant to be
  124 used instead of doing manual adjustments.
  125 
  126 - CONFIG=NULL, CONFIG=NULLI
  127   Anything that can be turned off is off.  MIME cannot.
  128   The latter adds and "require"s iconv(3) and adds the user interface
  129   strings.
  130 
  131 - CONFIG=MINIMAL
  132   Possibly what people want who need nothing but a MIME-capable mailx(1)
  133   and do not regret improved usability for the rare interactive use
  134   occasions.  Adds documentation strings, the built-in line editor (MLE)
  135   with history support and key bindings, error tracking, basic colour
  136   support and IDNA addresses, as well as generic spam filter support.
  137 
  138   "Require"s iconv(3), regex(3) and the dotlock helper.
  139 
  140 - CONFIG=NETSEND
  141   Sending messages directly to the mail provider via the SMTP protocol,
  142   instead of requiring a local mail-transfer-agent (MTA) who does.
  143 
  144   Adds SSL/TLS, SMTP, GSSAPI and .netrc file parsing on top of MINIMAL.
  145 
  146   "Require"s iconv(3), SSL/TLS, SMTP (sockets) and the dotlock helper.
  147 
  148 - CONFIG=MAXIMAL
  149   Like MINIMAL, but turns on all (other) options, also obsolete or
  150   redundant ones, but none of them required.
  151 
  152 1.1 What if configuration fails?
  153 --------------------------------
  154 
  155 The configuration process creates a directory ./.obj where the build
  156 will take place.  If anything goes wrong, it should be sufficient to
  157 simply remove this directory.  In there it will create some files named
  158 "mk-config.*":
  159 
  160 - mk-config.log  output generated by the configuration compile tests.
  161 - mk-config.lst  configuration (chosen option, programs, paths).
  162 - mk-config.h    C program header produced according to mk-config.lst.
  163 - mk-config.ev   A set of sh(1) variables for reproducible compile runs.
  164 - mk-config.inc  List of C header include paths, as compiler directives.
  165 - mk-config.lib  List of used library information, as compiler directives.
  166 
  167 Of special interest is mk-config.log since the error usually manifests
  168 here in textual output.  Maybe that makes it obvious what can be done
  169 (header files could not be found because of missing entries in
  170 $C_INCLUDE_PATH, libraries could not be linked because of incomplete
  171 $LD_LIBRARY_PATH, etc.).
  172 
  173 Otherwise it is getting complicated, and it would be appreciated if you
  174 would contact the mailing-list!
  175 
  176 1.2 What if building fails?
  177 ---------------------------
  178 
  179 Even worse!  This should not happen if configuration succeeded!  It
  180 would be very kind and highly appreciated if you would report this
  181 to the mailing-list.
  182 
  183 1.3 What if tests fail?
  184 -----------------------
  185 
  186 That would be a disaster.  Please contact the mailing-list!
  187 If you have used OPT_AUTOCC (the default) and a non-debug target, you
  188 could try to reconfigure with an additional cc_maxopt=1 on the command
  189 line and report whether that turns the green testing light on.
  190 
  191 Otherwise you could run the cc-test.sh script in --mae-test mode and
  192 invoke the failing tests (testing echoes the actual test names in
  193 brackets): this will produce output files of the form t.TESTXY in the
  194 .obj directory.  Please send these files to the mailing-list, possibly
  195 stored altogether in a compressed tar(1) file (the mailing-list has
  196 a message size restriction).  For example:
  197 
  198   $ ./cc-test.sh --mae-test ./s-nail localopts mbox
  199   $ tar -czf badtests.tar.gz .obj/t.*
  200 
  201 Thank you!
  202 (These output files will also be created by "make test" a.k.a. the
  203 --check-only mode of cc-test.sh if run in a S-nail repository.)
  204 
  205 1.4 How can i enable debugging?
  206 -------------------------------
  207 
  208 Please ensure OPT_DEBUG=yes is enabled during compilation, as in
  209 
  210   $ make CONFIG=MAXIMAL OPT_DEBUG=yes
  211 
  212 If OPT_AUTOCC is enabled then the build system should automatically
  213 adjust the compiler flags accordingly, please see make.rc for more.
  214 There is also a `devel'opment target which does most of this by itself:
  215 
  216   $ make devel
  217 
  218 OPT_DEBUG (`devel') will enable memory bound debug canaries and
  219 Not-Yet-Dead function graph listings etc.  Whereas the latter will try
  220 to write its listing into a file named after your favourite MUA in
  221 your $TMPDIR (or "/tmp" or "./", in order), falling back to STDERR shall
  222 creation of the file not be possible (we will not overwrite an existing
  223 file), the debug facilities in general make their appearance on the
  224 standard error channel; because this can be a quite long output, then,
  225 it is possibly a good idea to redirect it to a file:
  226 
  227   $ s-nail -dvv 2> error.log
  228 
  229 Should you really discover any problems with S-nail it would be very
  230 useful for development if you would contact the mailing-list!
  231 Thank you!
  232 
  233 2.0 Notes on building the latest release
  234 ----------------------------------------
  235 
  236 - All systems:
  237   * I have turned off -Wstrict-overflow warnings unless we are debug
  238     enabled (talking about OPT_AUTOCC=yes here): too noisy on some gcc.
  239   * There are warnings on unused returns from some I/O functions.
  240     These will vanish after the large v15 I/O and MIME rewrite.
  241   * Some "XYZ may be used uninitialized" warnings are logically false.
  242 
  243 - All 32-bit systems:
  244   * There _may_ be warnings about format strings, like, e.g.,
  245       auxlily.c:1610:10: warning: format '%lu' expects type 'long
  246       unsigned int', but argument 3 has type 'size_t'
  247     The codebase is ISO C89 which has no %z printf(3) format.
  248     However we try hard to detect the real type size and define the
  249     "PRI[du]Z" macros which end up with the correct size, which is
  250     also compile-time asserted (see the "MCTA(sizeof(size_t) == XZ)"
  251     statements in nail.h).
  252 
  253     By forcing ISO C99 mode when compiling these warnings vanish, e.g.,
  254     with gcc(1) and clang(1): with OPT_AUTOCC pass
  255     "EXTRA_CFLAGS=-std=c99", otherwise ensure -std=c99 in $CFLAGS.
  256 
  257 Development and/or regular tests:
  258 
  259 . AlpineLinux <https://www.alpinelinux.org/> (edge; x86-64).
  260 . ArchLinux <https://www.archlinux.org/> (~weekly updated; x86-64).
  261 . CRUX Linux <https://www.crux.nu/> (3.4; x86-64).
  262 . FreeBSD <https://www.freebsd.org/> (11.2; x86).
  263   - The tests iconv_mbyte_base64-4 and
  264     iconv_mbyte_base64-8 will fail because the ISO C function
  265     iswprint(3) will falsely claim that U+FF08 and U+FF09 (FULLWIDTH
  266     LEFT and RIGHT PARENTHESIS, respectively) are not printable, causing
  267     replacements.  This is a known bug, see
  268       <https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=225692>
  269 
  270 Occasional tests:
  271 
  272 . DragonFly BSD <https://www.dragonflybsd.org/> (5.2.1; x86-64).
  273   See FreeBSD for the two failing test cases.
  274 . NetBSD <https://www.netbsd.org/> (8.0_RC1; i386).
  275   - Test shcodec-unicode fails, like Solaris.  (Faulty Unicode ctype.)
  276 . OpenBSD <https://www.openbsd.org/> (6.3; x86).
  277 . Solaris <http://opencsw.org/>
  278   @ First of all: thanks to OpenCSW.org for offering SSH access to
  279     their Solaris build cluster!
  280   * With OPT_AUTOCC: we try to use Sun cc(1) whenever we find it.
  281     If your gcc(1) installation is doing alright you have to turn
  282     OPT_AUTOCC off and use $CC, $CFLAGS and $LDFLAGS.
  283   * Some notes collected on earlier trials:
  284     + We may forcefully disable stack protectors on SunOS/gcc because of
  285       linking errors seen in earlier tests.
  286     + If you get the compiler / system header installation error
  287         Undefined                       first referenced
  288          symbol                             in file
  289         __builtin_stdarg_start              auxlily.o
  290       then you have to overwrite this symbol with __builtin_va_start,
  291       e.g., in conjunction with OPT_AUTOCC add this:
  292        EXTRA_CFLAGS='-D__builtin_stdarg_start=__builtin_va_start'
  293   - On elder SunOS the test shcodec-unicode fails, like NetBSD.
  294 . Void Linux <https://www.voidlinux.eu/> (x86)
  295 
  296 # s-ts-mode