ecl/INSTALL

You will find detailed installation instructions in the ECL manual
       https://common-lisp.net/project/ecl/static/manual/Building-ECL.html
If you do not have access to the online version, follow the following recipies.

* Unix and similar platforms.
1. Type
   ./configure --help
   to get a list of the flags with which ECL can be configured.
2. Enter
   ./configure ...
   where "..." is the set of flags you have chosen.
3. Use "make" followed by "make install" to build and install ECL.

* Windows with Visual Studio C++ 2008
1. Open the Visual Studio x86 or x64 native tools command prompt
2. Enter the msvc directory
3. Read the file Makefile to find the configuration options. They
   typically have the form ECL_UNICODE=1, ECL_THREADS=1, etc
4. Enter
   nmake ...
   followed by zero or more of those options
5. Use "nmake install" to create a directory called "package" with ECL in it.
6. Move that directory wherever you need.

* Cross-compile for the android platform (from the UNIX machine)
1. Build the host ECL
   #+BEGIN_SRC shell-script
     # C99 complex numbers are not fully supported on Android
     ./configure ABI=32 CFLAGS="-m32 -g -O2" LDFLAGS="-m32 -g -O2"\
                 --prefix=`pwd`/ecl-android-host --disable-c99complex
     make -j9
     make install
     rm -r build
     export ECL_TO_RUN=`pwd`/ecl-android-host/bin/ecl
   #+END_SRC
2. Configure the toolchain (requires android-ndk version 15 or higher, known to work with version 17c)
   and export the necessary paths:
   #+BEGIN_SRC shell-script
     export NDK_PATH=/opt/android-ndk
     export ANDROID_API=23
     export TOOLCHAIN_PATH=`pwd`/android-toolchain
     ${NDK_PATH}/build/tools/make_standalone_toolchain.py --arch arm --install-dir ${TOOLCHAIN_PATH} --api ${ANDROID_API}
     export SYSROOT=${TOOLCHAIN_PATH}/sysroot
     export PATH=${TOOLCHAIN_PATH}/bin:$PATH
  #+END_SRC
3. Build and install the target library
   #+BEGIN_SRC shell-script
     # boehm GC is not compatible with ld.gold linker, force use of ld.bfd
     export LDFLAGS="--sysroot=${SYSROOT} -D__ANDROID_API__=${ANDROID_API} -fuse-ld=bfd"
     export CPPFLAGS="--sysroot=${SYSROOT} -D__ANDROID_API__=${ANDROID_API} -isystem ${SYSROOT}/usr/include/arm-linux-androideabi"
     export CC=arm-linux-androideabi-clang
     ./configure --host=arm-linux-androideabi \
                 --prefix=`pwd`/ecl-android \
                 --disable-c99complex \
                 --with-cross-config=`pwd`/src/util/android-arm.cross_config
     make -j9
     make install
   #+END_SRC
4. Library and assets in the ecl-android directory are ready to run on
   the Android system.

** Building ecl-android on Darwin (OSX)
If your host platform is darwin, then the host compiler should be
built with the Apple's GCC (not the GCC from Macports). Using the
MacPort command:
#+BEGIN_SRC shell-script
  sudo port select --set gcc none
#+END_SRC

Hint provided by Pascal J. Bourguignon.


* Cross-compile for the iOS platform (needs Xcode 11 or higher)
1. Build the host ECL
   #+BEGIN_SRC shell-script
     ./configure CFLAGS="-DECL_C_COMPATIBLE_VARIADIC_DISPATCH" --prefix=`pwd`/ecl-iOS-host --disable-c99complex
     make -j9
     make install
     rm -r build
     export ECL_TO_RUN=`pwd`/ecl-iOS-host/bin/ecl
   #+END_SRC
2. Configure the toolchain
   #+BEGIN_SRC shell-script
     export IOS_VERSION_MIN="8.0"
     export IOS_SDK_DIR="`xcode-select --print-path`/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/"

     export CC="clang"
     export CXX="clang++"

     export CFLAGS="-arch arm64 -miphoneos-version-min=${IOS_VERSION_MIN} -isysroot ${IOS_SDK_DIR}"
     export CFLAGS="$CFLAGS -pipe -Wno-trigraphs -Wreturn-type -Wunused-variable"
     export CFLAGS="$CFLAGS -fpascal-strings -fasm-blocks -fmessage-length=0 -fvisibility=hidden"
     export CFLAGS="$CFLAGS -O2 -DNO_ASM"

     export LD="ld"
     export LDFLAGS="-arch arm64 -pipe -std=c99 -gdwarf-2 -isysroot ${IOS_SDK_DIR}"
     export LIBS="-framework Foundation"
   #+END_SRC
3. Build and install the target library
   #+BEGIN_SRC shell-script
     export CFLAGS="$CFLAGS -DGC_DISABLE_INCREMENTAL -DECL_RWLOCK"
     export CXXFLAGS="$CFLAGS"
     ./configure --host=aarch64-apple-darwin \
                 --prefix=`pwd`/ecl-iOS \
                 --disable-c99complex \
                 --disable-shared \
                 --with-cross-config=`pwd`/src/util/iOS-arm64.cross_config
     make -j9
     make install
   #+END_SRC
4. Library and assets in the ecl-iOS directory are ready to run on
   the iOS system.

* Cross-compile for the WASM platform (via emscripten)

Emscripten target is a little fickle so keep in mind that:

- disable-shared is needed, because emcc does not recognize libecl.so (?)

- disable-tcp is needed, because accept can't be found (related to
  disable-shared? lack of -lsockets or something in this spirit?)

- select for interactive streams does not work, because reading operations are
  blocking (as they should be!), so there is no EOF returned -- clear-input will
  hang without a proper file-cnt

- to build emscripten you need to use their SDK that provides the toolchain, and
  set the environment variable EMSDK_PATH

1. Build the host ECL

#+begin_src shell-script
  ./configure ABI=32 CFLAGS="-m32 -g -O2 -DECL_C_COMPATIBLE_VARIADIC_DISPATCH" LDFLAGS="-m32 -g -O2" \
              --prefix=`pwd`/ecl-emscripten-host --disable-threads

  make -j16 && make install
  rm -rf build/
#+end_src

2. Configure the toolchain

Install the Emscripten SDK using the official instructions:

        https://emscripten.org/docs/getting_started/downloads.html

These build instructions were tested against ~emsdk 3.1.41~. If things doesn't
work try that version instead of ~latest~.

After that activate the toolchain and configure build flags:

#+begin_src shell-script
  source ${EMSDK_PATH}/emsdk_env.sh
  export ECL_TO_RUN=`pwd`/ecl-emscripten-host/bin/ecl
  # You may customize various emscripten flags here, i.e:
  # export LDFLAGS="-sASYNCIFY=1"
#+end_src

3. Build the core environment and install it

#+begin_src shell-script
  emconfigure ./configure \
              --host=wasm32-unknown-emscripten \
              --build=x86_64-pc-linux-gnu \
              --with-cross-config=`pwd`/src/util/wasm32-unknown-emscripten.cross_config \
              --prefix=`pwd`/ecl-emscripten \
              --with-tcp=no \
              --with-cmp=no

  emmake make && emmake make install

  # some files need to be copied manually
  cp build/bin/ecl.js build/bin/ecl.wasm ecl-emscripten/
#+end_src

4. ECL may be hosted on a web page. Assuming that you have quicklisp installed:

#+begin_src shell-script
  export WEBSERVER=`pwd`/src/util/webserver.lisp
  pushd ecl-emscripten/
  lisp --load $WEBSERVER
  # After the server is loaded run:
  # firefox localhost:8888/ecl.html
  popd
#+end_src

If the output does not show on the webpage then open the javascript console.
This is a default html website produced by emscripten.

5. Build an external program linked against libecl.so

The default stack size proposed by emscripten is 64KB. This is too little for
ECL, so when you build a program that is linked against libecl.so, then it is
imoprtant to specify a different size. For example:

#+begin_src shell-script
  emcc program.c -sSTACK_SIZE=1048576 libecl.so -I./ -o program.o
#+end_src