1This file presents 2* a list of platforms CLISP is known to run on, 3* special hints for some platforms, 4* hints for porting to new platforms. 5 6 7List of platforms 8================== 9 10* GNU and Unix platforms 11* macOS 12* Windows (both native Windows and Cygwin) 13 14 15Special hints for some platforms 16================================ 17 18 19* On Nokia N800 (Arm) running Linux: 20 21If you get a crash during loading of the first few lisp file (first GC), 22add "-DNO_GENERATIONAL_GC" to CFLAGS. 23If your modules do not work (clisp.h does not define "object" type), 24install GNU sed. 25 26 27* On ppc and ppc64 running Linux: 28 29If you get a crash during loading of the first few lisp file (first GC), 30add "-DNO_GENERATIONAL_GC" to CFLAGS. 31 32 33Porting to new platforms 34======================== 35 36The C compiler 37-------------- 38 39Choose a reliable C compiler. GNU gcc is a good bet. Generally, start the 40port with the least optimization settings regarding the compiler (-O0 in 41the CFLAGS) and the safest optimization settings regarding the CLISP source 42(configure with --enable-portability). 43 44Address space layout 45-------------------- 46 47Generally (except on 32-bit machines when configured with --enable-portability) 48CLISP tries to use memory mapping facilities (mmap on Unix, VirtualAlloc on 49Windows) in order to 50 - simplify memory management (a large block of memory is more efficient 51 to manage that a set of randomly distributed memory pages), 52 cf. macro SPVW_BLOCKS vs. SPVW_PAGES, 53 - support generational garbage collection, 54 cf. macro GENERATIONAL_GC, 55 - speed up type recognition by putting type tags into the pointers, 56 cf. macro TYPECODES vs. HEAPCODES. 57 58Such memory mapping requires knowledge about the address space layout. 59The configuration determines some parameters about the address space layout, 60such as: 61 checking for the code address range... 0x00000000 62 checking for the malloc address range... 0x01000000 63 checking for the shared library address range... 0xB6000000 64 checking for the stack address range... 0xBE000000 65 66If you need a deeper understanding of the address space layout, the following 67tools print a memory map (i.e. the virtual memory areas) of a running process: 68 * The '-mm' option: Run 69 $ ./lisp.run -mm 70 This option works on many, but not all platforms. 71 * OS dependent tools: Run an executable, look up its process ID (through "ps"), 72 then: 73 - On Linux: 74 $ cat /proc/$pid/maps 75 $ pmap $pid 76 - On Mac OS X: 77 $ vmmap -interleaved $pid 78 - On FreeBSD: 79 $ cat /proc/$pid/map 80 $ procstat -v $pid 81 - On NetBSD: 82 $ cat /proc/$pid/map 83 - On OpenBSD: 84 # procmap -p $pid 85 - On AIX: 86 $ procmap -S $pid 87 - On Solaris: 88 $ pmap $pid 89 90The stack address range is printed by these tools, but CLISP does not make 91assumptions about it. 92 93Verifying that all supported configurations work 94------------------------------------------------ 95 96There are a number of configurations of the memory management (different 97object representation, different GC algorithms, old_gc vs. multithread_gc, 98etc.). It is useful to verify that all such supported configurations work 99and which configuration cannot be supported on the particular platform, 100so that 101 - you get an overview of which features don't work in any configuration 102 (you can then disable this feature in lispbibl.d), 103 - you can be sure that there are no hidden bugs lurking, 104 - later regressions become apparent quickly. 105 106To do so: 1071) Get at least one configuration to at least build lisp.run without 108 compilation errors (--enable-portability is your best bet for this). 109 Then get an understanding of address space layout (see above). 1102) Add to lispbibl.d platform dependent sections: 111 - A section that defines MAPPABLE_ADDRESS_RANGE_START and 112 MAPPABLE_ADDRESS_RANGE_END. 113 - A section that defines the parameters for SINGLEMAP_MEMORY: 114 SINGLEMAP_ADDRESS_BASE, SINGLEMAP_TYPE_MASK, SINGLEMAP_oint_type_shift. 115 - A section that defines the parameters for ONE_FREE_BIT_HEAPCODES: 116 garcol_bit_o. 117 - A section that defines the parameters for TYPECODES_WITH_TRIVIALMAP. 118 - A section that defines the parameters for TYPECODES_WITH_MALLOC. 1193) Build the whole set of variants. 120 This is done through one of the commands 121 make -k -f Makefile.devel multibuild-porting32-gcc 122 make -k -f Makefile.devel multibuild-porting32-cc 123 make -k -f Makefile.devel multibuild-porting64-gcc 124 make -k -f Makefile.devel multibuild-porting64-cc 125 Pick the one that matches your platform bitness (32-bit or 64-bit 126 platform) and your compiler (GCC or compatible, e.g. clang, versus 127 vendor cc). 128 Before doing this, you need to set an environment variable 129 MULTIBUILD_32_OPTIONS (for the 32-bit target) or MULTIBUILD_64_OPTIONS 130 (for the 64-bit target), that contain configuration options, typically 131 --prefix, --with-libsigsegv-prefix, --with-libffcall-prefix options. 1324) Depending on the results, define *_WORKS macros in lispbibl.d: 133 - SINGLEMAP_WORKS, depending on the result of 134 build-porting*-spvw_pure_blocks 135 - HEAPCODES1BIT_WITH_TRIVIALMAP_WORKS, depending on the result of 136 build-porting*-one_free_bit_heapcodes-trivialmap 137 - HEAPCODES1BIT_WITH_MALLOC_WORKS, depending on the result of 138 build-porting*-one_free_bit_heapcodes-malloc 139 - KERNELVOID32_HEAPCODES_WORKS, depending on the result of 140 build-porting32-*-kernelvoid32_heapcodes 141 - GENERIC64C_HEAPCODES_WORKS, depending on the result of 142 build-porting64-*-generic64_heapcodes 143 - TYPECODES_WITH_TRIVIALMAP_WORKS, depending on the result of 144 build-porting*-typecodes-spvw_mixed_blocks-trivialmap 145 - TYPECODES_WITH_MALLOC_WORKS, depending on the result of 146 build-porting64-gcc-typecodes-spvw_pure_pages 147 build-porting64-gcc-typecodes-spvw_mixed_pages 148 build-porting64-gcc-typecodes-spvw_mixed_blocks-malloc 1495) Redo step 3. 150 Inspect all the build-porting*/cbcstep3.log and determine which failures 151 were justified and which were bugs that you can fix. 152 If you could fix bugs, repeat this step. 1536) Add to Makefile.devel a target multibuild-<platform> that contains all 154 configuration targets that should succeed. 1557) Run "make -k -f Makefile.devel multibuild-<platform>" and verify that 156 build-porting*/cbcstep3.log succeeded. 157 158Enabling optimizations that work 159-------------------------------- 160 161After you have performed "Verifying that all supported configurations work" 162(see above): 1631) In makemake.in add a section with platform dependent configuration flags. 164 You can start with the flags that get enabled when ${enable_portability} 165 is 'yes'. 1662) Remove at many de-optimization flags from this section as you can. 167 Then run 168 $ rm -rf build-porting* 169 $ make -k -f Makefile.devel multibuild-<platform> 170 If not all these builds succeeded (look at build-porting*/cbcstep3.log 171 again), re-enable some de-optimization flags and repeat this step. 172 173Quick porting 174------------- 175 176If you don't want to go through the (lengthy) process described in the sections 177above, you can alternatively make some educated guess about which configuration 178will likely work out. Here are tips for this approach. 179 180On 64-bit platforms, if you cannot identify a pattern for the address space 181layout, add -DGENERIC64_HEAPCODES -falign-functions=8 to the CFLAGS. 182 183If you get an error message concerning mapped memory, you should add 184-DNO_SINGLEMAP to the CFLAGS and recompile. Doing so introduces a tiny speed 185penalty. If you still get an error message concerning mapped memory, you 186should add -DNO_TRIVIALMAP to the CFLAGS and recompile. 187 188Other troubleshooting 189--------------------- 190 191Some options or optimizations are enabled through macros, conditionally 192defined in lispbibl.d. You can check which macros get defined in lispbibl.d 193by looking into lispbibl.h, assuming you are using gcc. For example: 194 make lispbibl.h 195 grep TYPECODES lispbibl.h 196 197If you get an error message mentioning "handle_fault", then generational GC 198is not working. Add -DNO_GENERATIONAL_GC to the CFLAGS and recompile. 199 200If you get an error message during the loading of the first 10 Lisp files, 201during the construction of the first .mem file, check the choice of 202setjmp/longjmp functions in lispbibl.d. 203 204If interpreted.mem was successfully generated, but lisp.run dumps core when 205loading .fas files, you should add -DSAFETY=3 to the CFLAGS and recompile. 206Find out which is the least SAFETY level that produces a working lisp.run and 207lispinit.mem, and tell me about it. 208 209