doc: Release update.
[mes.git] / HACKING
diff --git a/HACKING b/HACKING
index 2af5d6d7f2cdb651fa88909ca66b175c06b14aa4..047e2e3ad40a7d29d4d3713e5d6ef2a28c838771 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -1,8 +1,24 @@
--*-mode:org-*-
+                                                              -*- org -*-
+#+TITLE: Hacking GNU Mes
+
+Copyright © 2016,2017,2018 Jan (janneke) Nieuwenhuizen <janneke@gnu.org>
+
+  Copying and distribution of this file, with or without modification,
+  are permitted in any medium without royalty provided the copyright
+  notice and this notice are preserved.
 
 * SETUP
-    guix environment -l guix.scm     #64 bit + 32bit
-    guix environment --system=i686-linux -l guix.scm #32 bit only
+    guix environment -l .guix.scm     #64 bit + 32bit
+
+or
+
+    guix environment --system=i686-linux -l .guix.scm #32 bit only
+
+or
+
+    guix package --profile=~/.config/guix/mes --manifest=build-aux/manifest.scm
+    . ~/.config/guix/mes/etc/profile
+
 * BUILD
 There are two major modes to build Mes: true bootstrap and
 development.
@@ -10,79 +26,87 @@ development.
 ** DEVELOPMENT BUILD
 To help development we assume ./configure sets these variables for make
 
-   CC     -- gcc
-   CC32   -- i686-unknown-linux-gnu-gcc (or on x86, also gcc)
+   CC     -- gcc (or i686-unknown-linux-gnu-gcc sans libc)
    GUILE  -- guile
    HEX2   -- hex2
    MES    -- unset
    M1     -- M1
-   PREFIX -- ""
+   prefix -- ""
 
-Mes is supposed to serve as a full equivalent for Guile, however mes is much, much
-slower than guile.  That's why we usually don't use mes during development.
+Mes is supposed to serve as a full equivalent for Guile, however Mes
+is still about 2 to 10 times slower than Guile.  That's why we usually
+don't use Mes during development.
 
-gcc is used to verify the sanity of our C sources.
+Gcc is used to verify the sanity of our C sources.
 
 i686-unknown-linux-gnu-gcc is used to compare hex/assembly, to test
-the gcc variant of mes libc: lib/libc-gcc.c and steal ideas.
+the gcc variant of Mes C Libirary.
+Target prefix: x86-mes-gcc.
+
+gcc -nostdinc,-nostdlib is used to compare hex/assembly, to test the
+64bit variant of Mes C Library.  Target prefix: x86_64-mes-gcc.
 
-Guile is used to develop mescc, the C compiler in Scheme that during
-bootstrapping will be executed by mes.
+Guile is used to develop MesCC, the C compiler in Scheme that during
+bootstrapping will be executed by Mes.
 
 ** BOOTSTRAP BUILD
-In bootstrap mode, we don't have gcc (CC), we don't have pa 32 bit gcc
-(CC32), we have no guile (GUILE)...but we should have hex2, M1, and
-FIXME: mes.M1.
 
-mes is built from src/*.c and some out/src/*.h files that are snarfed from
-src/*.c by build-aux/mes-snarf.scm.
+    ./configure.sh [--prefix=PREFIX]
+    ./build.sh
+    ./install.sh
+
+In bootstrap mode, we don't have gcc (CC), we don't have a 32 bit gcc,
+we have no guile (GUILE)...but we should have hex2, M1, and mes.M1.
+That's a bootstrap problem which is currently ignored by using the
+mes-seed package.  mes.M1 will be produced by M2-Planet from mes.c.
 
-Running ./make.scm produces a `script' file.
 
 * ROADMAP
-** TODO 
+** TODO
 *** release 0.x, unsorted
-  - mes+mescc: compile a mes-tcc that can compile gcc-4.7.
-  - mes: prepare src/mes.c for M2-Planet transpiler.
-  - mes: use more efficient scheme continuation stack (wip-array?)
-  - mes: drop SCM stack in C / implement call/cc a la guile-1.8 setjmp?
-  - mescc: refactor type(/ptr?) system; expr->type and ast-type->type.
-  - mescc: refactor initializers.
-  - mescc: record and support function types, and thus foo ()->bar, *foo ().
-  - mescc: refactor switch statement to support unpatched tinycc.
-  - mes/mescc: bootstrap a minimal-Guile
-    + libguile/{eval,init,list,strings,values,..}.c
+  - mes: prepare src/mes.c for M2-Planet transpiler,
+    Jeremiah branched-out from mes; see https://github.com/oriansj/mes-m2.
+  - mes/mescc: proper docstrings, api reference documentation.
+  - replace bootstrap-binaries with Gash: bash, coreutils, grep, gzip,
+    sed, tar.
+  - mes: real module support, Guile compatible (define-module,
+    define-public, export).
+  - mescc: ARMv7/AArch64 support.
+*** after release 1.0
+  - replace initial gcc-2.95.3 with gcc-3.x or 4.x
+  - use 3rd party libc (ucLibc, dietlibc, ...) after Mes and reduce
+    need for bootstrappably-rich Mes C Library?
+  - mes/mescc: bootstrap a `bootstrap-Guile' before bootstrapping tcc?
+  - tcc: remove or upstream patches from tcc-boot.
+  - tcc: build 0.9.27 directly instead of via 0.9.26, see tinycc
+    wip-bootstrappable@0.9.27 branch
+  - mes/mescc: bootstrap a minimal-Guile?
+    + libguile/{eval,init,list,strings,values,..}.
     + ice-9/eval.scm
   - mescc: have mes-tcc pass all scaffold/tests, scaffold/tinycc tests.
-  - mescc: compile a mes-tcc that can compile gcc-4.7.
-  - mescc: refactor switch; support heterogeneous switch case.
-  - mescc: support sizeof any expr.
-  - mescc: support function-static.
-  - mescc: support/grok global static.
-  - mescc: support unsigned comparison, arithmetic.
-  - mescc: support long long.
-  - mescc: support bitfields.
-  - mescc: support floats.
-  - mescc: some success with 8cc,pcc,guile/libguile/eval.c.
-  - build: guile/guix/make.scm: add file-types, intermediate, hash all dependencies
-  - build: make.scm: imperative->declaritive
-  - mes: real module support, bonus for supporting Guile's define-module/define-public syntax.
-  - get full source syntax-case up (Andre van Tonder?) OR drop it.
-    https://srfi.schemers.org/srfi-72/srfi-72.html
-    psyntax/syntax-case and rewrite Nyacc without syntax-case+R7RS Ellipsis.
-  - mescc: split-off MesCC as as standalone Guile C compiler project.
-*** release 1.0
-  - replace GuixSD's bootstrap binaries for x86.
-  - add x86_64, replace GuixSD's bootstrap binaries for x86_64.
-  - more architectures?
+  - syntax-case bootstrap problem
+    + resolve portable syntax-case bootstrap, or
+    + get full source syntax-case up (Andre van Tonder?)
+      https://srfi.schemers.org/srfi-72/srfi-72.html, or
+    + ... drop it?
+  - mescc: the Hurd support.
 ** DONE
+*** 0.19 GNU mes now compiles TinyCC in ~8min and supports building Bash and GNU Tar.
+*** 0.18 GNU mes now supports GuixSD bootstrap (x86,x86_64) and has native x86_64 support.
+*** 0.17.1 GNU Mes now allows removing glibc, binutils and gcc from the GuixSD bootstrap.
+*** 0.17 GNU Mes is now an official GNU project and bootstraps gcc-4.7.4.
+*** 0.16.1 Mes now has info docs and installs ootb on Debian buster/testing.
+*** 0.16 Mes Lib C now bootstraps glibc-2.2.5, binutils-2.20.1, gcc-4.1.0.
+*** 0.15: MesCC now has a libc+gnu that supports compiling binutils-2.14, gcc-2.95.3 and glibc-2.2.5.
+*** 0.14: Mes+MesCC now compiles a slightly patched self-hosting tcc.
+*** 0.13: Mes+MesCC now compiles a modified, functional tcc.c (~25,000LOC) in 1h30'.
 *** 0.12: Mes+MesCC now compiles mes.c (~3000LOC) in ~4min.
 *** 0.11: MesCC now compiles a mes-tcc that passes 26/69 of mescc's C tests.
 *** 0.10: Mescc now compiles a mes-tcc that compiles a trivial C to a running a.out.
 *** 0.9: Mescc now writes M1 macro assembly files and compiles tcc.
 *** 0.8: Mescc now writes object files in stage0's labeled hex2 format.
 *** 0.7: Mescc supports -E, -c, -o options, include more complete set of header files,
-eenough to work on compiling tinycc's tcc.c albeit a somewhat modified version.
+enough to work on compiling tinycc's tcc.c albeit a somewhat modified version.
 *** 0.6: Work with unmodified, unbundled Nyacc; compile 33/55 tinycc's tests/test2 suite.
 *** 0.5: Mutual self-hosting Scheme interpreter and C compiler: mes.c and mescc,
          Support call-with-current-continuation, refactor catch/throw
@@ -91,12 +115,40 @@ eenough to work on compiling tinycc's tcc.c albeit a somewhat modified version.
 *** 0.2: Support psyntax
 *** 0.1: Mes eval/apply feature complete; support syntax-rules, compile main.c using LALR, dump ELF
 
+
+* DEBUG
+  MES_DEBUG=<level> mes
+** Levels
+  1) Informational:
+     - MODULEDIR
+     - included SCM modules and sources
+     - result of program
+     - gc stats at exit
+  2) opened files
+  3) runtime gc stats
+  4) detailed info
+     - parsed, expanded program
+     - list of builtins
+     - list of symbol
+     - opened input strings
+     - gc details
+  5) usage of opened input strings
+
+
 * Bugs
+** mes: performance, Mes is now 2-10x slower than Guile.
+** mes/mescc lack support for the Hurd.
+** mes: gcc-x86_64 compiled mes segfaults with small arena, or gc_up_arena.
+** mes: gcc-x86 compiled, tests/srfi-13.test number->string INT-MIN fails:
+test: number->string INT-MIN: fail
+expected: -2147483648
+actual: -./,),(-*,(
+** tcc: tcc-built lib/libc+tcc.c segfaults with mes, with tcc.
 ** mes: remove pmatch-car/pmatch-cdr hack.
+** mescc: softcode stack frame size, now hardcoded and very large
 ** mes+mescc: parse tcc.c->tcc.E works, compile tcc.E -> tcc.M1 segfaults.
-  time GUILE_LOAD_PATH=/home/janneke/src/nyacc/module:$GUILE_LOAD_PATH ../mes/scripts/mescc.mes -E -o tcc.E -I . -I ../mes/lib -I ../mes/include -D 'CONFIG_TCCDIR="usr/lib/tcc"' -D 'CONFIG_TCC_CRTPREFIX="usr/lib:{B}/lib:."' -D 'CONFIG_TCC_ELFINTERP="/gnu/store/70jxsnpffkl7fdb7qv398n8yi1a3w5nx-glibc-2.26.105-g0890d5379c/lib/ld-linux.so.2"' -D 'CONFIG_TCC_LIBPATHS="/home/janneke/src/tinycc/usr/lib:{B}/lib:."' -D 'CONFIG_TCC_SYSINCLUDEPATHS="../mes/include:usr/include:{B}/include"' -D CONFIG_USE_LIBGCC=1 -D 'TCC_LIBGCC="/home/janneke/src/tinycc/usr/lib/libc+tcc-gcc.mlibc-o"' -D CONFIG_TCC_STATIC=1 -D ONE_SOURCE=yes -D TCC_TARGET_I386=1 -D BOOTSTRAP=1 tcc.c
-  time GUILE_LOAD_PATH=/home/janneke/src/nyacc/module:$GUILE_LOAD_PATH MES_ARENA=200000000 ../mes/scripts/mescc.mes -c -o tcc.M1 tcc.E
-** mes: with-fluids: tests/fluids.test test 7 fails with Mes.
+  time GUILE_LOAD_PATH=/home/janneke/src/nyacc/module:$GUILE_LOAD_PATH ../mes/scripts/mescc -E -o tcc.E -I . -I ../mes/lib -I ../mes/include -D 'CONFIG_TCCDIR="usr/lib/tcc"' -D 'CONFIG_TCC_CRTPREFIX="usr/lib:{B}/lib:."' -D 'CONFIG_TCC_ELFINTERP="/gnu/store/70jxsnpffkl7fdb7qv398n8yi1a3w5nx-glibc-2.26.105-g0890d5379c/lib/ld-linux.so.2"' -D 'CONFIG_TCC_LIBPATHS="/home/janneke/src/tinycc/usr/lib:{B}/lib:."' -D 'CONFIG_TCC_SYSINCLUDEPATHS="../mes/include:usr/include:{B}/include"' -D CONFIG_USE_LIBGCC=1 -D 'TCC_LIBGCC="/home/janneke/src/tinycc/usr/lib/libc+tcc-gcc.mlibc-o"' -D CONFIG_TCC_STATIC=1 -D ONE_SOURCE=yes -D TCC_TARGET_I386=1 -D BOOTSTRAP=1 tcc.c
+  time GUILE_LOAD_PATH=/home/janneke/src/nyacc/module:$GUILE_LOAD_PATH MES_ARENA=200000000 ../mes/scripts/mescc -c -o tcc.M1 tcc.E
 ** mescc: 7n-struct-struct-array.c:  struct file f = {"first.h"};
 ** test/match.test ("nyacc-simple"): hygiene problem in match
 * OLD: Booting from LISP-1.5 into Mes
@@ -123,7 +175,7 @@ neat, Lisp/Scheme, bootstrapping and trusted binaries are probably not
 in scope as there is no mention of such things; only ML is mentioned
 while Guile is used for bootstrapping.
 
-* Assorted ideas and info 
+* Assorted ideas and info
 ** Using GDB on assembly/a.out
 info registers
 p/x $eax
@@ -134,6 +186,9 @@ b *0x804a79d
 ** Create memory dump with 32 bit Gcc compiled Mes
 make out/i686-unknown-linux-gnu-mes
 out/i686-unknown-linux-gnu-mes --dump < module/mes/read-0.mes > module/mes/read-0-32.mo
+
+x/s *((char **)($rsp+8))
+
 ** C parser/compiler
 *** [[https://savannah.gnu.org/projects/nyacc][nyacc]]
 *** PEG: [[http://piumarta.com/software/peg/][parse C using PEG]]
@@ -150,7 +205,7 @@ out/i686-unknown-linux-gnu-mes --dump < module/mes/read-0.mes > module/mes/read-
 ** SC - c as s-expressions
 sc: http://sph.mn/content/3d3
 ** RNRS
-*** [[http://www.scheme-reports.org/][Scheme Reports]] 
+*** [[http://www.scheme-reports.org/][Scheme Reports]]
 *** [[ftp://publications.ai.mit.edu/ai-publications/pdf/AIM-349.pdf][Scheme - Report on Scheme]]
 *** [[ftp://publications.ai.mit.edu/ai-publications/pdf/AIM-452.pdf][RRS - Revised Report on Scheme]]
 
@@ -201,4 +256,7 @@ https://miyuki.github.io/2017/10/04/gcc-archaeology-1.html
 ** rain1's Bootstrapping Wiki: https://bootstrapping.miraheze.org/wiki/Main_Page
 ** rain1's hex86
 https://notabug.org/rain1/hex86/src/master/tests/hex0b3.hex86
-
+** <pdewacht> janneke, have you ever tried testing mescc with csmith?  [10:55]
+** <pdewacht> e.g. as described here
+           https://jamey.thesharps.us/2016/07/15/testing-strategies-for-corrode/
+           ("Randomized testing with Csmith and C-Reduce")  [10:58]