Skip to content

Latest commit

 

History

History
208 lines (135 loc) · 6.08 KB

BUILDING.md

File metadata and controls

208 lines (135 loc) · 6.08 KB
Raw

How To Build

Summary

Supported platforms:

  • MacOS
  • FreeBSD
  • Linux-based systems (e.g Ubuntu, Centos)

Build Steps:

  • install dcc (go get github.com/atrn/dcc, see below)
  • build ici using make (gmake on BSDs)
  • install using make install prefix=/some/path

Overview

There are several ways to build ici. The official way, shown above, is the method I use. GNU make is used to direct things and another tool, dcc, looks after compilation, linking and library creation.

Building with make and dcc

The make and dcc method supports building ICI in a number of different configurations - standalone executable, static library and executable, or dynamic library and executable - and adds make targets to install ici and other tasks.

This method is described below.

Building with cmake

A very simple CMakeLists.txt is provided to build the standalone ICI interpreter executable. cmake support is minimal but can be used to generate files for IDEs and other build tools (ninja works well).

Run cmake to generate build files, e.g.,

$ cmake -Bbuild -H.

This will create a build directory with the cmake generated build files. ccmake can be used to adjust build settings. For more details see the cmake documentation.

Makefiles

Some conventional makefiles are located in the etc directory. These can be used as is or act as a starting point for creating better makefiles tailored to your environment.

Without make

A standalone executable build is essentially trivial on current UNIX-like systems. The following command is sufficient on the supported platforms,

$ c++ -std=c++14 -I. -UNDEBUG *.cc etc/main.cc -o ici

Building ICI with make and dcc

The supported build system for ICI uses GNU make and my compiler driver program, dcc. You likely already have GNU make or know where to get it. Installing dcc is straight forward.

Install dcc

dcc is open source (licensed under the GNU GPL v2) and available from https://github.com/atrn/dcc. dcc is written in Go and installation requires Go be installed (some platforms do this via their package manager otherwise Go can be obtained via golang.org). Installation is straight forward. Follow their instructions.

Assuming a conventional Go installation (i.e. you followed the instructions), installing dcc is done with the command,

$ go get github.com/atrn/dcc

By default go get will install the binary under your $GOPATH or ~/go/bin by default. If you've set $GOPATH I assume you know what you're doing and where the dcc executable resides.

Build

With dcc installed building ICI is done via make,

$ make

make directs the build process and invokes dcc for compilation, linking and library creation.

To configure the build process a number of make macros can be set, either via the command or by editing the Makefile. The makefile is simple (since dcc does the real work) and reasonably well commented.

Compiler options

Compiler and linker options and libraries are defined in files read by dcc which are stored in the .dcc directory. The CXXFLAGS file define compiler options, the LIBS files has library names and LDFLAGS the linker options.

There are a number of CXXFLAGS files under .dcc which can be selected via the make cxxflags macro. An example is given next.

Targets and macros

Typically development workflows are supported by make targets and macros. Some common operations are shown below:

Build a standalone executable,

$ make build=exe

(this is the default).

Build a static library

This creates a static library, libici.a and corresponding ici.h header file. The ici executable is linked against that library.

$ make build=lib

Build a dynamic library

This creates a dynamic library, e.g. libici.so on ELF-platforms, an ici.h header file and an ici executable linked against the dynamic library.

$ make build=dll

make clean

Clean up files generated by the build.

$ make clean

This deletes the files generated by all the different types of builds.

Create a debug-mode interpreter

Build an interpreter with debugging options enabled,

$ make debug

Note, the debugging checks make the interpreter far slower than that without the checks.

Link Time Optimization

LTO, aka whole program optimization, may create a faster interpreter. The lto target builds an LTO version of the interpreter executable.

$ make cxxflags=CXXFLAGS.lto build=exe dccflags=--verbose
... lots of output

Per-Platform configuration

More control over the configuration is available by setting the CONFIG_FILE macro to the, quoted, name of a header file that defines the interpreter's configuration.

The file named by CONFIG_FILE is included by the fwd.h header file (which is included by all ici source files). If CONFIG_FILE is not set fwd.h selects a file for the host, if it can determine it.

The standard conf header files are located in the conf directory.

Installation

On supported platforms,

$ make install [build=<build-type>] [prefix=<some-path>]

Installing requires copying the executable somewhere, creating the ICI lib directory and copying the core .ici files to that location.

  • ici -> $(prefix)/bin/ici
  • ici-core*.ici -> $(prefix)/lib/ici

If the selected build type creates a static or dyynamic ICI library that file is copied to the $(prefix)/lib directory and a header file, ici.h created for users of that library. The ici.h and icistr-setup.h files are are copied to the $(prefix)/include directory

The installed files are,

  • prefix/bin/ici
  • prefix/include/ici.h
  • prefix/include/icistr-setup.h
  • prefix/lib/libici.a
  • prefix/lib/libici.so
  • prefix/lib/ici/ici-core.ici
  • prefix/lib/ici/ici-core1.ici
  • prefix/lib/ici/ici-core2.ici
  • prefix/lib/ici/ici-core3.ici
  • prefix/lib/ici/ici-core4.ici
  • prefix/lib/ici/ici-core5.ici
  • prefix/lib/ici/ici-core6.ici
  • prefix/lib/ici/ici-core7.ici
  • prefix/lib/ici/ici-core8.ici

The full-install target