trap-representation / toc Goto Github PK

+----------------------------------------+
| Translation guide for the toc compiler |
+----------------------------------------+

This version of toc can only geterate output that are compatible with nightVM. Check ./toc/src/ for the source of the toc compiler.

The toc compiler conforms to ISO/IEC 2899:2011. However, it depends on certain implementation guarantees; for example, during translation, it is assumed that a preprocessing directive of the form
# include "q-char-sequence" new-line
searches for the named source file the way it is defined in SUSv4-2018 4.13 (Pathname resolution).

Toc is most likely NOT strictly conforming, because chances are, certain minimum implementation limits are exceeded (though I have not verified that yet).

Toc tries to depend on as less implementation-defined stuff as possible. If you have a C11 implementation, it will very likely be able to translate the source files, and the program should have the expected observable behavior.

In ./toc/src/nvm_sources.h, set the header-name following the identifier TOC_NVM_IMPLEMENTATION_H, such that the construct
#include TOC_NVM_IMPLEMENTATION_H
includes the source file implementation.h as defined in nightVM. Same goes for TOC_NVM_OPCODES_H and TOC_NVM_ALLOC_H, which must designate the source files opcodes.h and alloc.h (in nightVM) respectively.

In ./toc/src/toc.c (main), set the pointer to char designated by the identifier stdlib_pathname to point to a string that denotes the output generated by translating the implementation of the standard library, such that the aforementioned output can be opened with fopen(stdlib_pathname, "rb").

In ./toc/src/resolve_imports.c (resolve_imports), set the pointer to char designated by the identifier file_name -- for each header provided by Chlore's standard library -- to denote the respective header files defined by said standard library (the files suffixed with .chlore in ./lib/src/), such that those files can be opened with fopen(file_name, "r").

In ./toc/src/toc.c, the string-literal following the identifier ESFF23xCOM_STRL designates the comment that is written to the output, if an ESFF23x executable is being generated. The string literal can be changed to write a custom comment to the generated ESFF executable.

After you have made the appropriate changes, just translate the following source files: ./toc/src/toc.c, ./toc/src/clean_up_routines.c, ./toc/src/code_gen.c, ./toc/src/resolve_imports.c, ./toc/src/lexer.c, ./toc/src/parser.c, ./toc/src/tables.c, ./toc/src/verify.c, ./toc/src/write_error.c and ./toc/src/buf_ops.c, and link them.

+------------------------------------------------------------+
| Getting the implementation of the standard library working |
+------------------------------------------------------------+

NOTE: The implementation of the standard library is still highly work-in-progress.

Check ./lib/src/ for the source of the implementation of the standard library.

In ./lib/src/libchlore.c, set the header-name following the identifier LIB_NVM_IMPLEMENTATION_H, such that the construct
#include LIB_NVM_IMPLEMENTATION_H
includes the source file implementation.h as defined in nightVM.

./lib/src/libchlore.c can be translated to generate a library.

In ./lib/src/stdlib.chloreh, set the string-constant following the identifier STDLIB_ID such that it designates the output generated by translating ./lib/src/libchlore.c into a library.

As of now, it conforms to the ISO/IEC 2899:2011 standard with the assumption that the system interfaces provided by SUSv4-2018 are available, and during translation, a preprocessing directive of the form as mentioned in the installation guide for the toc compiler, searches for the named source file the way it is defined in SUSv4-2018 4.13 (Pathname resolution). It might not exactly be strictly POSIX conforming, since some minimum implementation limits might have been exceeded.

+----------------------------+
| Translating the easier way |
+----------------------------+

If you're using a SUSv4-2018 compliant system and are fine with toc and the implementation of the standard library being put in /usr/local/bin/ and /usr/local/lib/ respectively, you can check out the TRANSLATE_DEF file for instructions. The instructions are guaranteed to work for clang 14.0.0 and gcc 11.4.0; however, for other implementations, the commands may or may not work the way they're meant to, depending on how certain arugments are parsed/interpreted.