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.
long boot1_offset — an offset into boot1_path 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.
long boot1_len — an optional length in bytes for the first boot image, which is used as a hint for loading the boot file if non-zero. If this hint is provided, it must be at least as large as the boot image bytes, and it must be no longer than the file size after the boot image offset.
const char * boot2_path — like boot1_path, but for the image that contains compiler functionality, normally called "scheme.boot".
long boot2_offset — an offset into boot2_path to read for the second boot image.
long boot2_len — boot1_len, an optional length in bytes for the second boot image.
const char * boot3_path — like boot1_path, but for the image that contains Racket functionality, normally called "racket.boot".
long boot3_offset — boot1_len, an offset into boot2_path to read for the third boot image.
long boot3_len — an optional length in bytes for the third boot image.
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