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