5 Starting and Declaring Initial Modules (CS)

5 Starting and Declaring Initial Modules (CS)🔗ℹ

As sketched in Embedding into a Program (CS), and embedded instance of Racket CS is started with racket_boot. Functions such as racket_embedded_load_bytes help to initialize a Racket namespace with already-compiled modules.

For functions and struct fields that contain a path in char* form, the path is treated as UTF-8 encoded on Windows.

5.1 Boot and Configuration🔗ℹ

void

racket_boot

(

racket_boot_arguments_t* boot_args)

Initializes a Racket CS instance. A main thread is created and then suspended, waiting for further evaluation via racket_apply, racket_eval, and similar functions.

A racket_boot_arguments_t struct contains fields to specify how racket_boot should initialize a Racket instance. New fields may be added in the future, but in that case, a 0 or NULL value for a field will imply backward-compatible default.

Fields in racket_boot_arguments_t:

const char * boot1_path — a path to a file containing a Chez Scheme image file with base functionality. Normally, the file is called "petite.boot". The path should contain a directory separator, otherwise Chez Scheme will consult its own search path. The racket_get_self_exe_path and/or racket_path_replace_filename functions may be helpful to construct the path.
void * boot1_data — an alternative to boot1_path, a pointer to the boot file’s content in memory. When using this field, the boot1_len field must be supplied as non-zero. Only one of boot1_path and boot1_data can be non-NULL.
Added in version 8.13.0.4.
long boot1_offset — an offset into boot1_path or boot1_data to read for the first boot image, which allows boot images to be combined with other data in a single file. The image as distributed is self-terminating, so no size or ending offset is needed (except that boot1_len must be at least as large as the image when supplied via boot1_data).
long boot1_len — an length in bytes for the first boot image, which is optional and used as a hint if non-zero when the boot image is supplied via boot1_path. If this length is provided, it must be at least as large as the boot image in bytes, and it must be no larger than the file size or readable memory after the boot image offset.
const char * boot2_path — like boot1_path, but for the image that contains compiler functionality, normally called "scheme.boot".
void * boot2_data — like boot1_data, but an alternative to boot2_path. When using this field, the boot2_len field must be supplied as non-zero.
Added in version 8.13.0.4.
long boot2_offset — like boot1_offset, an offset into boot2_path or boot2_data to read for the second boot image.
long boot2_len — like boot1_len, a length in bytes for the second boot image, optional when the boot image is supplied via boot2_path.
const char * boot3_path — like boot1_path, but for the image that contains Racket functionality, normally called "racket.boot".
void * boot3_data — like boot1_data, but an alternative to boot3_path. When using this field, the boot3_len field must be supplied as non-zero.
Added in version 8.13.0.4.
long boot3_offset — like boot1_offset, an offset into boot2_path or boot3_path to read for the third boot image.
long boot3_len — like boot1_len, a length in bytes for the third boot image, optional when the boot image is supplied via boot3_path.
int argc and char ** argv — command-line arguments to be processed the same as for a stand-alone racket invocation. If argv is NULL, the command line -n is used, which loads boot files without taking any further action.
const char * exec_file — a path to use for (system-type 'exec-file), usually argv[0] using the argv delivered to a program’s main. This field must not be NULL.
const char * run_file — a path to use for (system-type 'run-file). If the field is NULL, the value of exec_file is used.
const char * collects_dir — a path to use as the main "collects" directory for locating library collections. If this field holds NULL or "", then the library-collection search path is initialized as empty.
const char * config_dir — a path to used as an "etc" directory that holds configuration information, including information about installed packages. If the value if NULL, "etc" is used.
wchar_t * dll_dir — a path used to find DLLs, such as iconv support. Note that this path uses wide characters, not a UTF-8 byte encoding.
int cs_compiled_subdir — A true value indicates that the use-compiled-file-paths parameter should be initialized to have a platform-specific subdirectory of "compiled", which is used for a Racket CS installation that overlays a Racket BC installation.

5.2 Loading Racket Modules🔗ℹ

void	racket_embedded_load_bytes	(	const char* code,
			uptr len,
			int as_predefined)

void		racket_embedded_load_file	(	const char* path,
				int as_predefined)

void	racket_embedded_load_file_region	(	const char* path,
			uptr start,
			uptr end,
			int as_predefined)

These functions evaluate Racket code, either in memory as code or loaded from path, in the initial Racket thread. The intent is that the code is already compiled. Normally, also, the contains module declarations. The raco ctool --c-mods and raco ctool --mods commands generate code suitable for loading with these functions, and --c-mods mode generates C code that calls racket_embedded_load_bytes.

If as_predefined is true, then the code is loaded during the creation of any new Racket place in the new place, so that modules declared by the code are loaded in the new place, too.

These functions are not meant to be called in C code that was called from Racket. See also Calling Procedures (CS) for a discussion of entry points versus re-entry points.

5.3 Startup Path Helpers🔗ℹ

char*

racket_get_self_exe_path

(

const char* argv0)

Returns a path to the current process’s executable. The arg0 argument should be the executable name delivered to main, which may or may not be used depending on the operating system and environment. The result is a string that is freshly allocated with malloc, and it will be an absolute path unless all attempts to find an absolute path fail.

On Windows, the argv0 argument is always ignored, and the result path is UTF-8 encoded.

Added in version 8.7.0.11.

char*		racket_path_replace_filename	(	const char* path,
				const char* new_filename)

Returns a path like path, but with the filename path replaced by new_filename. The new_filename argument does not have to be an immediate filename; it can be relative path that ends in a filename. The result is a string that is freshly allocated with malloc.

Added in version 8.7.0.11.

I	Inside Racket CS
II	Inside Racket BC (3m and CGC)
III	Appendices
	Index

1	Overview (CS)
2	Embedding into a Program (CS)
3	Values and Types (CS)
4	Calling Procedures (CS)
5	Starting and Declaring Initial Modules (CS)
6	Evaluation and Running Modules (CS)
7	Managing OS-Level Threads (CS)

5.1	Boot and Configuration
5.2	Loading Racket Modules
5.3	Startup Path Helpers