Downloading

To download eĿlipsis you need git. The repository can be found at

‍https://gitlab.inria.fr/gustedt/ellipsis

You should probably not clone the whole repository, the branch that holds the expanded documentation is quite large (> 1GiB). The main branch should be completely sufficient if you want to work with eĿlipsis. To download the sources as a subdirectory ellipsis in your current directory you could use

git clone --single-branch https://gitlab.inria.fr/gustedt/ellipsis

This only downloads some MiB onto your disk.

Compiling

eĿlipsis is only tested on a Linux platform, but should work equally well on other POSIX platforms.

Compiling eĿlipsis needs a compiler that is conforming to C23, for example recent gcc or clang should do. Besides that not much is needed. Just go into the sources directory and compile. For example this one launches 4 parallel processes to compile an link eĿlipsis.

cd sources
make distclean
CC=gcc-14 make -j 4

The distclean step is important when you compile for the first time, because when checking the project out with git some time stamps for the generated sources (see below) may be misleading.

As usual you may play around with the compiler you are using and with compiler flags, for example

CC=gcc-14 CFLAGS='-O3 -march=native -fanalyzer -g -Wall' make -j 4

to fully optimize and enable gcc's static analyzer. The resulting executable bin/ellipsis has no binary dependencies other then system libraries.

To test ellipsis on its own generic source in sources/generic you may launch

make -B generate-all

This should run eĿlipsis to produce many of the sources, but at the end nothing in the sources/ directory but white space should have changed. If you have astyle installed you may beautify the sources by doing

make beautify

Then,

git status

should show no changes. If you are not able to do the "beautify" step, the difference should only be whitespace.

Configuration

EĿlipsis configures itself a program startup time. That is where it is decided for which language and compiler platform we are working today. If you'd like to use eĿlipsis for a compiler that we don't know, yet, you'd have to look into the configuration files in the "../include" directory. In particular C needs some work here, since knowledge abut the specific platform has to be present during preprocessing. This concerns first of all knowledge about integer types:

The the type char may or may not have negative values. This influences for example if a character literal '\xFF' has a positive (255) or negative (-1) value in #if constructs. The default assumption here is that CHAR_MIN is -128 and CHAR_MAX is 127. If not you may set the macros __CHAR_MIN__ and __CHAR_MAX__ from the environment.
The same problem arises for WCHAR_MIN and WCHAR_MAX and character literals of the form L'\xFFFFFFFF'. Here the assumption is that wchar_t is a signed type with 32 bit.
Other integer types don't have a direct influence on the behavior of the preprocessor, but still the _WIDTH, _MIN and _MAX macros have to be provided correctly.

Note that the wrapper ellipsis-gnuc.sh guesses all of these by querying your original preprocessor, so if you use that there is no need to do anything in particular.

Another feature that has to be known by the preprocessor are attributes (a C23 language feature). This is some bunch of data that has to be integrated into the preprocessor such that it may provide correct results for the __has_c_attribute builtin. Again, for the wrapper ellipsis-gnuc.sh this is produced automatically from a list of possible attributes of which we know.

To have run-time access to configuration files and extensions, eĿlipsis uses several approaches:

These files are embedded into the ellipsis executable by means of #embed. It then has access to them via standard include notation such as <ellipsis-do.dirs>. By this, the executable can be placed anywhere in your file system and does not need any special configuration directory. This feature uses a POSIX specific function fmemopen to open a stream over a storage buffer.
If you want to experiment or change these files you may switch of this default via the environment variable ELLIPSIS_HASH_INCLUDE_DISABLE.
- At startup the executable then tries to determine is effective location in the file system and searches for "../include" from there. This feature uses OS specific extensions (POSIX and (untested) Windows).
- If this is not found you should still be able to use an include commandline argument -I to point ellipsis in the right direction.

I personally use eĿlipsis mostly as separate phase producing intermediate source files. If you want to use it as a direct replacement of the preprocessor that comes with your compiler, there still might be some rough edges.

There is now a replacement drop-in ellipsis-gnuc.sh that enables eĿlipsis as a preprocessor for C compilers that that are compatible with gcc to some extent, in particular all recent gcc and clang versions. So when you use this, the painful creation of configuration headers for new compiler versions is not needed.

Running

The executable that is produced is named bin/ellipsis. For constraints of moving this executable around, please see above.

EĿlipsis understands some of the usual command line arguments for C compilers,

option	needs argument	meaning
`-D`	yes	Define a macro. Name and parameter list are separated from the definition by a `=` character.
`-U`	yes	Undefine a macro.
`-I`	yes	Set an include directory.
`-x`	yes	Set an input language.
`-v`	no	Be verbose for the output.
`-d`	no	Dump some debug information.

and may also react to the setting of some environment variables, see ellipsis-environment.dirs

An argument that is not one of the above options (or the associated argument) is supposed to be a file name for the first source. A file extension may be used to determine the input language. This can be overwritten by the -x option. Language independent source files may be included as we go, e.g 〈ellipsis-do.dirs〉.

See also: Supported languages; ellipsis-do.dirs