.. highlight:: bash Configuring Sprite ================== The build system must first be configured by running ``configure``. That script finds, verifies, and (optionally) installs prerequisites. ``configure`` Manual -------------------- .. include:: configure-usage.rst Configuration Options --------------------- Sprite relies on several external programs. ``configure`` searches PATH for these, using a default name for each program. To adjust this behavior, supply one or more ``--with-*`` options or, equivalently, set the corresponding environment variable(s). An absolute path may be supplied, or the name to search for can be changed. These options are summarized in the following table: +---------------------------+----------------+--------------------+---------------------------------+ | Option | Environment | Default | Description | | | Variable | | | +===========================+================+====================+=================================+ | ``--with-cc`` | CC | ``gcc`` | Selects the C compiler | +---------------------------+----------------+--------------------+---------------------------------+ | ``--with-ccache`` | CCACHE | none | Puts ccache in front of the | | | | | compilers (optional) | +---------------------------+----------------+--------------------+---------------------------------+ | ``--with-cxx`` | CXX | ``g++`` | Selects the C++ compiler | +---------------------------+----------------+--------------------+---------------------------------+ | ``--with-cxx-postinstall``| CXX | ``g++`` | Selects the C++ compiler that | | | | | the installation uses to | | | | | compile Curry modules | | | | | (``tools/cxx``) | +---------------------------+----------------+--------------------+---------------------------------+ | ``--with-curry-frontend`` | CURRY_FRONTEND | ``pakcs-frontend`` | Selects the Curry front end. | | | | of PAKCS | Both routes need it. | +---------------------------+----------------+--------------------+---------------------------------+ | ``--with-icurry`` | ICURRY | none | Selects icurry, the alternative | | | | | route to ICurry (optional) | +---------------------------+----------------+--------------------+---------------------------------+ | ``--with-pakcs`` | PAKCS | ``pakcs`` | Selects PAKCS. An empty value | | | | | leaves it out | +---------------------------+----------------+--------------------+---------------------------------+ | ``--with-prolog`` | PROLOG | ``swipl`` | Selects Prolog | +---------------------------+----------------+--------------------+---------------------------------+ | ``--with-python`` | PYTHON | ``python3`` | Selects Python | +---------------------------+----------------+--------------------+---------------------------------+ The other options of ``configure`` fall into three groups. The prerequisite options check or install the external programs: ``--check-prereqs`` lists what is missing, ``--install-prereqs`` installs it and configures, ``--install-prereqs-only`` installs it alone, ``-y`` or ``--yes`` skips the confirmation, and ``--pip-nosudo`` is accepted for compatibility. ``-D`` or ``--doc`` adds the prerequisites of the documentation to the check, ``-f`` or ``--fast`` skips the expensive checks, and ``-i`` or ``--interactive`` asks for each setting. The build options, ``--jobs`` and ``--with-default-backend``, are described under `Build options`_. The development options are ``--cache``, which turns the caches of the toolchain on (``all``, ``icurry`` or ``json``; see ``SPRITE_CACHE_FILE`` under :doc:`/CommandLineInterface/EnvironmentVariables`), and ``--curry2icurry``, which selects the route from Curry to ICurry. Sprite translates Curry to ICurry in three steps: the Curry front end of PAKCS writes FlatCurry, the binding optimization rewrites that file in place, and Sprite's own code translates it to ICurry. The ``icurry`` program of the Curry Package Manager does the last step as well and is kept as an alternative; it needs the front end too, which Sprite runs first. ``configure`` records ``icurry`` only when you pass ``--with-icurry``. The option ``--curry2icurry`` names the route Sprite uses by default; the environment variable ``SPRITE_CURRY2ICURRY`` overrides that choice at run time. PAKCS itself is optional. Sprite needs its front end, which ``--with-curry-frontend`` can name directly, and the functional tests use ``pakcs`` as the oracle. ``--with-pakcs ''`` builds without PAKCS; the intermediate directories under ``.curry`` then take their names from the pinned release, ``pakcs-3.4.1``, so the committed ICurry files stay valid. The conda recipe under ``conda/`` builds this way; see ``conda/README.md``. For example, suppose Python 3.14 is installed but it is not the system default. Say:: ./configure --with-python=python3.14 [args...] If you have a custom build of Python not in PATH, you might say:: ./configure --with-python=/path/to/python [args...] To use the Clang compilers (searching PATH for them), one might say:: ./configure --with-cc=clang --with-cxx=clang++ [args...] If CC and CXX were set in the environment, this would happen anyway. Build options ------------- ``configure --jobs N`` sets the number of jobs that ``make`` runs at once. ``--jobs auto`` gives one job per processor, counted when ``make`` starts. It is the default; ``--jobs 1`` is a serial build. ``configure`` writes the value to ``Make.config`` as ``JOBS``, so ``make stage`` runs in parallel without ``-j``. A ``-j`` on the ``make`` command line wins, and so does ``make JOBS=N``. ``configure --with-ccache`` puts ccache in front of the compilers. The build compiles every object through ccache. The compiler of the installation, ``tools/cxx``, becomes a script that runs ccache in front of the post-install compiler, so the code of the C++ backend compiles through ccache as well. The value names the program (``--with-ccache=PATH``); by default ``configure`` searches PATH for ``ccache``. ccache changes nothing in the output of the compiler, and the ABI stamps of compiled modules do not depend on it. To share one cache between several copies of the source tree, set ``base_dir`` in the ccache configuration to a common parent directory. ``configure --with-default-backend NAME`` names the backend Sprite uses when no flag names one. ``cxx``, the C++ backend, is the default. ``configure`` writes the value to ``Make.config`` as ``DEFAULT_BACKEND``, and ``make stage`` writes it to the installation as ``sysconfig/default_backend``, where the interpreter flag ``backend`` reads its default. See :doc:`/CommandLineInterface/EnvironmentVariables` and :doc:`WithoutCompiler`. The setting for development work is:: ./configure --jobs auto --with-ccache [args...] Checking Prerequisites ---------------------- Sprite needs few programs. At build time: Python 3.14 with its development files, a C++ compiler (``g++``) with GNU make and binutils, and the Curry front end of PAKCS 3.4.1, ``bin/pakcs-frontend``. At run time: the same Python, the front end, and, for the C++ backend, the compiler. The C++ runtime uses the C++17 standard library alone; Boost is not needed. Optional: ``ccache``, ``icurry``, PAKCS as the oracle of the functional tests (it runs on SWI-Prolog), ``numpy`` for certain tests, Sphinx for the documentation, and GNU time for the benchmark harness. Once you have determined your configuration options, check the prerequisites:: ./configure [your-config-options...] --check-prereqs If ``configure`` reports problems, you may need to: 1. Adjust PATH; 2. Change configuation options; or 3. Install missing software. ``configure`` can attempt to install missing software for you. If you are satisfied with the steps proposed by ``./configure --check-prereqs`` then say:: ./configure [your-config-options...] --install-prereqs-only --yes Omit ``--yes`` if you prefer to confirm each step. To install these yourself, follow the instructions at the links below: * Python 3.14 with development files. - The `deadsnakes PPA `__ is a good source. Be sure to install the -dev package: install ``python3.14`` `AND` ``python3.14-dev``. * `PAKCS 3.4.1 `__ - The binary distribution includes the Curry front end, ``bin/pakcs-frontend``, the one program of PAKCS that Sprite runs. - Prolog (`SWI `__ or `SICStus `__) runs ``pakcs`` itself: the build of the saved states of the binary distribution, and the test oracle. Sprite runs no Prolog. - `Haskell stack `__ builds PAKCS from source. The binary distribution does not need it, and neither does Sprite. * Optional: `ICurry Compiler 3.1.0 `__, the alternative route from Curry to ICurry. Setting the Configuration ------------------------- Once the prerequisite check succeeds, run ``configure`` once more to set the configuration:: ./configure [your-config-options...] This creates a file ``Make.config`` containing the configuration settings. Inspect this file and make adjustments, if you like. To install prerequisites and configure in one step, say:: ./configure [your-config-options...] --install-prereqs [--yes]