1# @(#)README.compile 1.48 21/05/23 Copyright 1997-2021 J. Schilling
2
3Short overview for those who don't read manuals:
4
5 Calling configure manually is outdated because this is a task of the
6 makefile system.
7
8 There is no 'configure', simply call 'make' on the top level
9 directory.
10
11 *****
12 If you do not have a recent "smake" on your machine, you may first
13 need to compile and install a recent "smake".
14
15 In order to get a recent "smake" source, it is recommended to fetch
16 the "schilytools" tarball. If your local make program is not able to
17 automatically compile a bootstrap smake program in the "psmake"
18 directory from "schilytools", please read the file "BOOTSTRAP".
19 *****
20
21
22 ***** If this does not work for you, read the rest of this file *****
23 ***** If you have any problem, also first read the topic specific *****
24 ***** README.* files (e.g. README.linux for Linux problems). *****
25
26 All results in general will be placed into a directory named
27 OBJ/<arch-name>/ in the current projects leaf directory.
28
29 You **need** either the Schily "smake" program, the SunPRO make
30 that is included in "schilytools" and typically installed in
31 /opt/schily/bin/make and /opt/schily/bin/dmake, the SunPRO make
32 from /usr/bin/make (SunOS 4.x) or /usr/ccs/bin/make (SunOS 5.x)
33 or GNU make to compile this program. Read READMEs/README.gmake for
34 more information on gmake and a list of the most annoying bugs in gmake.
35
36 All other make programs are either not smart enough or have bugs.
37
38 My "smake" source is at:
39
40 https://sourceforge.net/projects/s-make/files/
41
42 It is easy to compile and doesn't need a working make program
43 on your machine. If you don't have a working "make" program on the
44 machine where you like to compile "smake" read the file "BOOTSTRAP".
45
46 If you have the choice between all three make programs, the
47 preference would be
48
49 1) smake (preferred)
50 2) Schily SunPRO make (preferred over (3))
51 3) SunPRO make
52 4) GNU make (this is the last resort)
53
54 Important notice: "smake" that comes with SGI/IRIX will not work!!!
55 This is not the Schily "smake" but rather a dumb make program from SGI.
56
57 ***** If you are on a platform that is not yet known by the *****
58 ***** Schily makefilesystem you cannot use GNU make. *****
59 ***** In this case, the automake features of smake are required. *****
60
61 Note that GNU make has major bugs on various platforms and thus cannot
62 be used at all on VMS and OS/2. GNU make on Cygwin causes problems
63 because it does not deal with spaces and newlines correctly. Given that
64 GNU make did not fix accepted bugs reported more than 20 years ago,
65 GNU make is not recommended.
66
67 Please read the README's for your operating system too.
68
69 WARNING
70 Do not use 'mc' to extract the tar file!
71 All mc versions before 4.0.14 cannot extract symbolic links correctly.
72
73 The versions of WinZip that support tar archives cannot be used either.
74 The reason is that they don't support symbolic links.
75 Star and Gnutar do support symbolic links even on win32 systems.
76 To support symbolic links on win32, you need to link with the
77 Cygwin32 POSIX library.
78
79 To unpack an archive, use:
80
81 gzip -d < some-arch.tar.gz | tar xpf -
82
83 Replace 'some-arch.tar.gz' by the actual archive name.
84
85 If your platform does not support hard links or symbolic links, you
86 first need to compile "star" and then call:
87
88 star -xp -copy-links < some-arch.tar.gz
89
90 If your platform does not support hard links but supports
91 symbolic links, you only need to call the command above once.
92 If your platform does not support symbolic links, you need to call
93 the command twice because a symbolic link may occur in the archive
94 before the file it points to.
95
96
97
98Here comes the long form:
99
100
101PREFACE:
102
103 Calling configure manually is outdated because this is a task of the
104 makefile system.
105
106 You don't have to call configure with this make file system.
107
108 Calling 'make' or 'make all' on the top level directory will create
109 all needed targets. Calling 'make install' will install all needed
110 files.
111
112 This program uses a new makefilesystem, introduced in 1993. This
113 makefilesystem uses techniques and ideas from the 1980s and 1990s,
114 is designed in a modular way and allows sources to be combined in a
115 modular way. For mor information on the modular features read
116 README.SSPM.
117
118 The makefilesystem is optimized for a program called 'smake'
119 Copyright 1985 by J�rg Schilling, but SunPro make (the make program
120 that comes with SunOS >= 4.0 and Solaris) as well as newer versions
121 of GNU make will work also. BSDmake could be made working, if it
122 supports pattern matching rules correctly.
123
124 The makefile system allows simultaneous compilation on a wide
125 variety of target systems if the source tree is accessible via NFS.
126
127
128Finding Compilation Results:
129
130 To allow simultaneous compilations, all binaries and results of a
131 'compilation' in any form are placed in sub-directories. This includes
132 automatically generated include files. Results will in general be
133 placed into a directory named OBJ/<arch-name>/ in the current project's
134 leaf directory, libraries will be placed into a directory called
135 libs/<arch-name>/ that is located in the source tree root directory.
136
137 <arch-name> will be something like 'sparc-sunos5-cc'
138
139 This is the main reason why simultaneous compilation is possible on
140 all supported platforms if the source is mounted via NFS.
141
142
143How to compile:
144
145 To compile a system or sub-system, simply enter 'smake', 'dmake', 'make'
146 or 'Gmake'. Compilation may be initialized at any point of the source
147 tree of a system.
148
149 WARNING: If compilation is started in a sub tree, only all objects
150 in that sub tree will be made. This usually excludes needed libraries.
151 NOTE: Compilation may not be started in a subdirectory unless a make
152 call from inside the directory "inc" has been run before.
153
154 NOTE: The "schilytools" source tree and the "smake" source tree come
155 with a "smake" bootstrap environment that uses Makefile as a trampoline
156 and SMakefile as the major makefile in the project root directory.
157 If you like to use a make program other than smake from the project
158 root directory without the bootstrap trampoline, use
159 "$MAKE -f SMakefile", e.g.
160
161 dmake -f SMakefile
162
163 On sub directories, "-f SMakefile" is neither needed nor useful.
164
165 Add other command line options or command line parameters if needed.
166
167How to compile with fully visible commands:
168
169 Call:
170
171 smake NOECHO=
172
173 and the @ in front of rule commands will be replaced by the empty
174 string. This causes the make program to print commands before
175 executing them to help debugging.
176
177How to compile in parallel mode:
178
179 The smake program does not yet support parallel compilation.
180
181 The dmake program supports parallel compilation. If you like the
182 default number of parallel jobs, just call 'dmake'. If you like
183 a different number, call 'dmake -j #', where # is the number of
184 parallel jobs.
185
186 Note that dmake collects the output from different jobs and prints
187 them in a way that does not interleave. For the Schily variant of
188 the dmake program, the Schily Makefilesystem by default disables the
189 job headers in the output. If you like to see them, call:
190
191 dmake DMAKE_OUTPUT_MODE=TXT1
192
193 The gmake program supports parallel mode, but does not separate the
194 output. If you get error or warning messages, you usually will be
195 confused by the mixture of the output. Recent gmake versions added
196 an option to separate the output from various jobs. Have a look
197 at the man page.
198
199
200How to run unit tests:
201
202 First call "smake" or "dmake" to compile everything and then run:
203
204 smake tests
205
206 at the top level directory or in any project sub-directory that
207 implements unit tests.
208
209 If you like to avoid the expensive random tests for programs like
210 "patch" or "sccs", you may disable the random tests by calling:
211
212 NO_RANDOM=TRUE smake tests
213
214
215How to install results:
216
217 To install the product of a compilation in your system, call:
218
219 smake install
220
221 at top level. The binaries will usually be installed in
222 /opt/schily/bin. The directory /opt/<vendor-name>/ has been agreed
223 on by all major UNIX vendors in 1989. Unfortunately, still not all
224 vendors follow this agreement.
225
226 If you want to change the default installation directory, edit the
227 appropriate (system dependent) files in the DEFAULTS directory
228 (e.g. DEFAULTS/Defaults.sunos5).
229
230 ***** If "smake install" doesn't do anything, you are on a broken *****
231 ***** File System. Remove the file INSTALL in this case (the FS *****
232 ***** does not handle upper/lower case characters correctly). *****
233 ***** This is true for all DOS based filesystems and for Apple's *****
234 ***** HFS+ filesystem. *****
235
236
237Using a different installation directory:
238
239 If your system does not yet use the standard installation path in
240
241 /opt/<vendor>
242
243 or if you don't like this installation directory, you can easily
244 change the installation directory. You may edit the DEFAULTS file
245 for your system and modify the macro INS_BASE.
246
247 You may use a different installation directory without editing the
248 DEFAULTS files. If you like to install everything in the deprecated path
249 /usr/local, the next paragraph describes the procedure.
250
251 If your make program supports to propagate make macros to sub make
252 programs which is the case for recent smake releases as well as for a
253 recent gnumake or a recent SunPro Make from the schilytools:
254
255 smake INS_BASE=/usr/local install
256 or
257 gmake INS_BASE=/usr/local install
258
259 If your make program doesn't propagate make macros (e.g. the
260 unmaintained SunPRO make variant from Sun/Oracle), call:
261
262 env INS_BASE=/usr/local make -e install
263
264 Note that INS_BASE=/usr/local needs to be specified for every operation
265 that compiles or links programs, as the path may be stored inside the
266 binaries. It is not sufficient to use INS_BASE=x for a "make install".
267 If you by mistake did already compile, call "make clean" before using
268 INS_BASE=x for compiling.
269
270 The location for the root specific configuratin files is controlled
271 via the INS_RBASE= make macro. The default vaulue for this macro is "/".
272 If you like to install global default configuration files into
273 /usr/local/etc instead of /etc, you need to spefify INS_RBASE=/usr/local
274
275 Note that some binaries have $(INS_BASE) and $(INS_RBASE) compiled into.
276 If you like to like to modify the compiled-in path values, call:
277
278 smake clean
279 smake INS_BASE=/usr/local INS_RBASE=/usr/local
280
281
282Setting up a different Link mode:
283
284 The following link modes are available:
285
286 static statical linking as in historical UNIX
287
288 dynamic dynamic linking as introduced by SunOS
289 in 1987, Microsoft's DLLs, ...
290 The knowledge on how to achieve this for
291 a particular platform is hidden in the
292 makefile system.
293
294 profiled Linking against profiled libraries.
295 Profiled libraries are prepared for the
296 use with "gprof" (introduced by BSD in the
297 late 1970s).
298
299 The makefile system sets up a default linkmode in the platform
300 related defaults file (typically in the file DEFAULTS/Defaults.<platform>)
301 in the projects root directory. This is done with the entry:
302
303 DEFLINKMODE= <linkmode>
304
305 A different linkmode may be selected at compile/link time by e.g. calling:
306
307 smake LINKMODE=dynamic
308
309 If there are already existing binaries, call:
310
311 smake relink LINKMODE=dynamic
312
313 instead.
314
315
316Compiling a different ELF RUNPATH into the binaries:
317
318 In order to allow binaries to work correctly even if the shared
319 libraries are not in the default search path of the runtime linker,
320 a RUNPATH needs to be set.
321
322 The ELF RUNPATH is by default derived from $(INS_BASE). If you like to
323 set INS_BASE=/usr and create binaries that do not include a RUNPATH at all,
324 call:
325
326 smake relink RUNPATH=
327
328
329Using a different man path prefix:
330
331 Manual pages are by default installed under:
332
333 $(INS_BASE)/$(MANBASE)/man
334 and MANBASE=share
335
336 If you like a different prefix for man pages, call:
337
338 smake DEFMANBASE=something install
339
340 to install man pages into $(INS_BASE)/something/man/*
341
342 If you like to install man pages under $(INS_BASE)/man/*, call
343
344 smake DEFMANBASE=. install
345
346Installing stripped binaries:
347
348 If you like to install stripped binaries via "smake install", call:
349
350 smake STRIPFLAGS=-s install
351
352 This calls "strip" on every final install path for all executable
353 binaries.
354
355Installing to a prototype directory to implement package creation staging:
356
357 If you like to create a prototype directory tree that is used as an
358 intermediate store for package creation, use the DESTDIR macro:
359
360 smake INS_BASE=/usr/local DESTDIR=/tmp install
361
362 This will compile in "/usr/local" as prefix into all related binaries
363 and then create a usr/local tree below /tmp (i.e. /tmp/usr/local).
364
365 Note that you need to call "smake clean" before in case that the code
366 was previously compiled with different defaults with regards to INS_BASE
367
368Setting different default directory permissions for install directories:
369
370 All directories that are created by the Schily makefile system in the
371 target directory path when
372
373 smake install
374
375 is called system use a special default 022 that is in DEFINSUMASK=
376 This causes all directories in the target install path to be created
377 with 0755 permissions.
378
379 All other directories that are created by the Schily makefile system
380 use a single global default 002 that is in DEFUMASK=
381
382 If you like to create install directories with e.g. 0775 permissions,
383 call:
384
385 smake DEFINSUMASK=002 install
386
387Using a different C compiler:
388
389 The *compiler family* is configured via the CCOM= make macro. This
390 selects a whole set of related macros that are needed to support a
391 specific compiler family.
392
393 The *compiler family* usually defines a C compiler and a related
394 C++ compiler.
395
396 If the configured default compiler family is not present on the current
397 machine, the makefilesystem will try an automatic fallback to GCC. For
398 this reason, in most cases, you will not need to manually select a
399 compiler.
400
401 The default compiler family can be modified in the files in the
402 DEFAULT directory. If you want to have a different compiler family
403 for one compilation, call:
404
405 make CCOM=gcc
406 or
407 make CCOM=cc
408
409 This works even when your make program doesn't propagate make macros.
410
411
412Creating 64 bit executables on Solaris:
413
414 Simply call:
415
416 make CCOM=gcc64
417 or
418 make CCOM=cc64
419
420 It is not clear if GCC already supports other platforms in 64 bit mode.
421 As all GCC versions before 3.1 did emit hundreds of compilation
422 warnings related to 64 bit bugs when compiling itself, so there may be
423 other platforms are not supported in 64 bit mode.
424
425Creating executables using the Sun Studio compiler on Linux:
426
427 Simply call:
428
429 make CCOM=suncc
430
431 If the compilation does not work, try:
432
433 mkdir /opt/sunstudio12/prod/include/cc/linux
434 cp /usr/include/linux/types.h /opt/sunstudio12/prod/include/cc/linux
435
436 Then edit /opt/sunstudio12/prod/include/cc/linux/types.h and remove all
437 lines like: "#if defined(__GNUC__) && !defined(__STRICT_ANSI__)"
438 as well as the related #endif.
439
440Creating executables using the clang compiler:
441
442 Simply call:
443
444 make CCOM=clang
445
446 And in order to intentionally create 32 bit or 64 bit binaries, call:
447
448 make CCOM=clang64
449 or
450 make CCOM=clang64
451
452
453Using a different compiler binary name:
454
455 Call:
456
457 make CC=/opt/instrumented/bin/cc
458
459 Note that all knowledge about the options of a compiler is derived
460 from the CCOM= variable, so if you like to use an instrumented gcc
461 variant, you may like to call:
462
463 make CCOM=gcc CC=fluffy-gcc
464
465 You may use CC="fluffy-gcc fluffy-gcc-specific options" if you like
466 to enforce specific options with the compiler. See hints on cross
467 compilation below.
468
469Avoiding to compile C++ based projects:
470
471 Call:
472 make C++BUILD=off
473
474
475Getting help from the make file system:
476
477 For a list of targets call:
478
479 make .help
480
481 .help is a special target that prints help for the makefile system.
482
483
484Getting more information on the make file system:
485
486 The man page makefiles.4 located in man/man4/makefiles.4 contains
487 the documentation on general use and for leaf makefiles.
488
489 The man page makerules.4 located in man/man4/makerules.4 contains
490 the documentation for system programmers who want to modify
491 the make rules of the makefile system.
492
493 For further information read
494
495 http://sf.net/projects/schilytools/files/makefiles/PortableSoftware.ps.gz
496
497
498Hints for compilation:
499
500 The makefile system is optimized for 'smake'. Smake will give the
501 fastest processing and best debugging output.
502
503 SunPro make will work as is. GNU make need some special preparation.
504
505 Read READMEs/README.gmake for more information on gmake.
506
507 To use GNU make create a file called 'Gmake' in your search path
508 that contains:
509
510 #!/bin/sh
511 MAKEPROG=gmake
512 export MAKEPROG
513 exec gmake "$@"
514
515 and call 'Gmake' instead of gmake. On Linux, there is no gmake, the
516 program installed as 'make' on Linux is really a gmake.
517
518 'Gmake' and 'Gmake.linux' are part of this distribution.
519
520 Some versions of gmake are very buggy. There are e.g. versions of gmake
521 on some architectures that will not correctly recognize the default
522 target. In this case, call 'make all' or '../Gmake all'.
523
524 Note that pseudo error messages from gmake similar to:
525
526 gmake[1]: Entering directory `cdrtools-1.10/conf'
527 ../RULES/rules.cnf:58: ../incs/sparc-sunos5-cc/Inull: No such file or directory
528 ../RULES/rules.cnf:59: ../incs/sparc-sunos5-cc/rules.cnf: No such file or directory
529
530 are a result of a bug in GNU make. The make file system itself is
531 correct (as you could prove by using smake).
532 If your gmake version still has this bug, send a bug report to:
533
534 "Paul D. Smith" <psmith@gnu.org>
535
536 He is the current GNU make maintainer.
537
538 If you like to use 'smake', please always compile it from source.
539 The packages are located on:
540
541 https://sourceforge.net/projects/s-make/files/alpha/
542
543 Smake has a -D flag to see the actual makefile source used
544 and a -d flag that gives easy to read debugging info. Use smake -xM
545 to get a makefile dependency list. Try smake -help
546
547
548Compiling the project using engineering defaults:
549
550 The defaults found in the directory DEFAULTS are configured to
551 give minimum warnings. This is made because many people will
552 be irritated by warning messages and because the GNU C compiler
553 will give warnings for perfectly correct and portable C code.
554
555 If you want to port code to new platforms or do engineering
556 on the code, you should use the alternate set of defaults found
557 in the directory DEFAULTS_ENG.
558 You may do this permanently by renaming the directories or
559 for one compilation by calling:
560
561 make DEFAULTSDIR=DEFAULTS_ENG
562
563 Note however, that some GCC versions print a lot of wrong warnings
564 in this mode. Well known problems with GCC warnings are:
565
566 - The recursive printf format "%r" that is in use since ~ 1980
567 is not supported and causes a lot of incorrect warnings as
568 GCC does not know that "%r" takes 2 parameters.
569
570 - The standard C construct "(void) read(fd, buf, sizeof (buf))"
571 is flagged by some versions of GCC even though the void cast
572 is a clear expression of the fact that the return code from read
573 is intentionally ignored. This may cause many useless warnings
574 for last resort error messages used in programs.
575
576
577Compiling the project to allow debugging with dbx/gdb:
578
579 If you like to compile with debugging information for dbx or gdb,
580 call:
581
582 make clean
583 make COPTX=-g LDOPTX=-g
584
585 If your debugger does not like optimized binaries, call something
586 like:
587
588 make "COPTX=-g -xO0" LDOPTX=-g
589 or
590 make "COPTX=-g -O0" LDOPTX=-g
591
592 depending on the option system used by your C compiler.
593
594
595Compiling the project to allow performance monitoring with gprof from BSD:
596
597 If you like to compile for performance monitoriing with gprof,
598 call:
599
600 make clean
601 make COPTX=-xpg LDOPTX=-xpg LINKMODE=profiled
602
603 or
604 make COPTX=-pg LDOPTX=-pg LINKMODE=profiled
605
606 depending on the option system used by your C compiler.
607
608
609Creating Blastwave packages:
610
611 Call:
612 .clean
613 smake -f Mcsw
614
615 You need the program "fakeroot" and will find the results
616 in packages/<arch-dir>.
617
618 Note that a single program source tree will allow you to create
619 packages like CSWstar but not the packages CSWschilybase and
620 CSWschilyutils on which CSWstar depends.
621
622
623
624
625 If you want to see an example, please have a look at the "star"
626 source. It may be found on:
627
628 http://sourceforge.net/projects/s-tar/files/
629
630 Have a look at the manual page, it is included in the distribution.
631 Install the manual page with
632
633 make install first and include /opt/schily/man in your MANPATH
634
635 Note that some systems (e.g. Solaris 2.x) require you either to call
636 /usr/lib/makewhatis /opt/schily/man or to call
637
638 man -F <man-page-name>
639
640
641Compiling in a cross compilation environment:
642
643 The Schily autoconf system has been enhanced to support cross
644 compilation. Schily autoconf is based on GNU autoconf-2.13 and
645 GNU autoconf does not support cross compilation because it needs
646 to run scripts on the target system for some of the tests.
647
648 The "configure" script that is delivered with the Schily makefile
649 system runs more than 770 tests and approx. 70 of them need to be
650 run on the target system.
651
652 The Schily autoconf system now supports a method to run these ~70
653 tests natively on a target system. You either need a target machine
654 with remote login features or you need an emulator with a method to
655 copy files into the emulated system and to run binaries on the
656 emulated system as e.g. the Android emulator.
657
658 We currently deliver three scripts for "remote" execution of
659 programs on the target system:
660
661 runrmt_ssh runs the commands remove via ssh
662 runrmt_rsh runs the commands remove via rsh
663 runrmt_android runs the commands remove via the debug bridge
664
665 If you need to remotely run programs on a system that is not
666 supported by one of the three scripts, you need to modify one
667 of them to match your needs.
668
669 To enable Cross Compilation use the following environment variables:
670
671 CONFIG_RMTCALL= Set up to point to a script that does
672 the remote execution, e.g.:
673
674 CONFIG_RMTCALL=`pwd`/conf/runrmt_ssh
675
676 CONFIG_RMTHOST= Set up to point to your remote host, e.g.:
677
678 CONFIG_RMTHOST=hostname
679 or
680 CONFIG_RMTHOST=user@hostname
681
682 use a dummy if you like to use something
683 like the Android emulator.
684
685 CONFIG_RMTDEBUG= Set to something non-null in order to
686 let the remote execution script mark
687 remote comands. This will result in
688 configure messages like:
689
690 checking bits in minor device number... REMOTE 8
691
692 If you cannot run commands on the target
693 platform, you may set:
694
695 CONFIG_RMTDEBUG=true
696 CONFIG_RMTCALL=:
697
698 carefully watch for the "REMOTE" flagged test
699 output and later manually edit the file:
700
701 incs/<arch-dir>/xconfig.h
702
703 Do not forget to manually edit the files:
704
705 incs/<arch-dir>/align.h
706 and
707 incs/<arch-dir>/avoffset.h
708
709 Note that smake includes automake features that automatically
710 retrieve system ID information. For this reason, you need to overwrite
711 related macros from the command line if you like to do a
712 cross compilation.
713
714 Related make macros:
715
716 K_ARCH= # (sun4v) Kernel ARCH filled from uname -m / arch -k
717 M_ARCH= # (sun4) Machine filled from arch
718 P_ARCH= # (sparc) CPU ARCH filled from uname -p / mach
719 OSNAME= # sunos, linux, ....
720 OSREL= # 5.11
721 OSVERSION= # snv_130
722 CCOM= # generic compiler name (e.g. "gcc")
723 CC= # compiler to call (name for binary)
724 CC_COM= # compiler to call (name + basic args)
725
726 ARCH= overwrites M_ARCH and P_ARCH
727
728 It is usually sufficient to set ARCH and OSNAME.
729
730 In order to use a cross compiler environment instead of a native compiler,
731 set the make macro CC_COM or CC to something different than "cc".
732
733 If you are on Linux and like to compile for Android, do the following:
734
735 1) set up CC acording to the instructions from the cross compiler
736 tool chain. Important: you need to read the information for your
737 tool chain. A working setup may look similar to:
738
739 NDK=/home/joerg/android-ndk-r7
740 SYSROOT=\$NDK/platforms/android-14/arch-arm
741 CC="\$NDK/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86/bin/arm-linux-androideabi-gcc --sysroot=\$SYSROOT"
742 export NDK
743 export SYSROOT
744 export CC
745
746
747 2) set environment variables CONFIG_RMTCALL / CONFIG_RMTHOST, e.g.:
748 setenv CONFIG_RMTCALL `pwd`/conf/runrmt_android
749 setenv CONFIG_RMTHOST NONE
750
751 3) call smake:
752
753 smake ARCH=armv5 OSNAME=linux CCOM=gcc "CC_COM=$CC"
754
755 or
756
757 smake ARCH=armv5 OSNAME=linux CCOM=gcc "CC=$CC"
758
759
760Compiling with the address sanitizer:
761
762 Be careful with a compiler enhancement called "address sanitizer".
763
764 First a note: the address sanitizer needs a lot of memory when in
765 64-bit mode. For this reason, it is recommended to run the tests
766 in 32-bit mode as it may be impossible to provide a sufficient amount
767 of memory for the 64-bit mode.
768
769 1) The address sanitizer may cause autoconf to behave incorrectly in
770 case that the compiler options used by the "configure" run include the
771 address sanitizer. It seems that in addition, the address sanitizer
772 adds more libraries to the link list and as a result prevents
773 the correct autoconf decision on whether a specific library from
774 a "configure" test is needed by some binaries.
775
776 If you are not sure about the current state of the source tree, start
777 with calling:
778
779 ./.clean
780
781 in the top level source directory. This makes the source tree to behave
782 as if if was recently unpacked from the tar archive.
783
784 Then run e.g.:
785
786 cd inc/
787 smake CCOM=gcc32
788 cd ..
789
790 to prepare the auto-configuration without using the address sanitizer.
791 This special treatment is needed as the assumptions in the address
792 sanitizer would not allow us to run the autoconfiguration code
793 correctly.
794
795 2) The address sanitizer by default ignores installed SIGSEGV handlers
796 and thus ignores the intention of the author of the code.
797
798 The correct behavior may be switched on via setting the environment
799 variable:
800
801 ASAN_OPTIONS=allow_user_segv_handler=true
802
803 As a result, the command line to compile the code after the
804 auto-configuration has been done as mentioned above is:
805
806 ASAN_OPTIONS=allow_user_segv_handler=true smake CCOM=gcc32 COPTX="-g -O0 -fsanitize=address" LDOPTX="-g -fsanitize=address"
807
808 3) If you are on Linux, do not forget to call "ulimit -c unlimited",
809 before calling the binary. This is needed as the default on Linux is
810 not to create a core file.
811
812 4) Set the environment ASAN_OPTIONS= for the execution of the binary
813 to control the behavior of the Address Sanitizer while the binary
814 is run.
815
816 If you like to disable the memory leak detection because your program
817 is a short running program that intentionally does not free() resources
818 before calling exit(), use:
819
820 ASAN_OPTIONS=allow_user_segv_handler=true:detect_leaks=0
821
822 If you also like to get a core dump on error to debug, you may like
823 to use:
824
825 ASAN_OPTIONS=allow_user_segv_handler=true:detect_leaks=0:abort_on_error=1
826
827 Note that the Address Sanitizer disables the creation of a core file
828 for 64 bit binaries as the tables used by the Address Sanitizer may
829 cause the core file to have a size of 16 TB.
830
831
832Compiling with the "Americal fuzzy lop":
833
834 Follow the instruction from above for the address sanitizer, but
835 use this command line to call the compiler:
836
837 ASAN_OPTIONS=allow_user_segv_handler=true AFL_HARDEN=1 AFL_USE_ASAN=1 smake CC=afl-gcc CCC=afl-g++ CCOM=gcc32
838
839 or, if using clang:
840
841 ASAN_OPTIONS=allow_user_segv_handler=true AFL_HARDEN=1 AFL_USE_ASAN=1 smake CC=afl-clang-fast CCC=afl-clang-fast++ CCOM=clang32
842
843
844Author:
845
846Joerg Schilling
847D-13353 Berlin
848Germany
849
850Email: joerg@schily.net
851
852Please mail bugs and suggestions to me.
853