On this page:
5.1 Boot and Configuration
5.2 Loading Racket Modules
5.3 Startup Path Helpers

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:

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.