{"size": 2370, "ext": "scrbl", "max_stars_repo_path": "pkgs/racket-doc/scribblings/raco/c-mods.scrbl", "max_stars_repo_name": "joshuafitzmorris/racket", "max_stars_repo_stars_event_min_datetime": "2018-07-05T21:18:24.000Z", "max_stars_repo_stars_event_max_datetime": "2021-06-04T14:48:37.000Z", "max_issues_repo_path": "pkgs/racket-doc/scribblings/raco/c-mods.scrbl", "max_issues_repo_name": "joshuafitzmorris/racket", "max_issues_repo_issues_event_min_datetime": "2017-05-10T07:33:20.000Z", "max_issues_repo_issues_event_max_datetime": "2018-07-19T15:49:46.000Z", "max_forks_repo_path": "pkgs/racket-doc/scribblings/raco/c-mods.scrbl", "max_forks_repo_name": "joshuafitzmorris/racket", "max_forks_repo_forks_event_min_datetime": "2016-04-25T11:47:57.000Z", "max_forks_repo_forks_event_max_datetime": "2017-05-09T14:52:48.000Z"}
{"max_stars_count": 4, "max_issues_count": 9, "max_forks_count": 3, "avg_line_length": 40.8620689655, "max_line_length": 70, "alphanum_fraction": 0.741350211}
#lang scribble/doc
@(require scribble/manual
          "common.rkt"
          scribble/bnf)

@title[#:tag "c-mods"]{Embedding Modules via C}

@margin-note{@exec{raco ctool} is provided by the @filepath{cext-lib}
                package.}

The @DFlag{c-mods} mode for @exec{raco ctool} takes a set of Racket
modules and generates a C source file that can be used as part of
program that embeds the Racket run-time system. See @secref[#:doc
inside-doc "embedding"] in @other-manual[inside-doc] for an
explanation of embedding programs.

The generated source file embeds the specified modules, and it defines
a @tt{declare_modules} function that puts the module declarations into
a namespace. Thus, using the output of @exec{raco ctool --c-mods}, a
program can embed Racket with a set of modules so that it does not
need a @filepath{collects} directory to load modules at run time.

If the embedded modules refer to runtime files, the files can be
gathered by supplying the @DFlag{runtime} argument to @exec{raco ctool
--cmods}, specifying a directory @nonterm{dir} to hold the files.
Normally, @nonterm{dir} is a relative path, and files are found at run
time in @nonterm{dir} relative to the executable, but a separate path
(usually relative) for run time can be specified with
@DFlag{runtime-access}.


Typically, @exec{raco ctool --c-mods} is used with @DPFlag{lib} to
specify a collection-based module path. For example,

@commandline{raco ctool --c-mods base.c ++lib racket/base}

generates a @filepath{base.c} whose @tt{declare_modules} function
makes @racketmodname[racket/base] available for use via the
@tt{scheme_namespace_require} or @tt{scheme_dynamic_require} functions
within the embedding application.

When a module file is provided to @exec{raco ctool --c-mods}, then
@tt{declare_modules} declares a module with the symbolic name of the
module file. For example, 

@commandline{raco ctool --c-mods base.c hello.rkt}

creates a @tt{declare_modules} that defines the module
@racket['hello], which could be required into the current namespace
with @racket[(namespace-require ''hello)] or similarly at the C level:

@verbatim[#:indent 2]{
  p = scheme_make_pair(scheme_intern_symbol("quote"),
                       scheme_make_pair(scheme_intern_symbol("hello"),
                                        scheme_make_null()));
  scheme_namespace_require(p);
}
