Initialization Macros

Macros
#define	REPY_PREINIT_ADD_NRM_TO_ALL_INTERPRETERS
	Adds this .nrm file to Python's module search path.
#define	REPY_ADD_NRM_TO_MAIN_INTERPRETER
	Adds this .nrm file to the main Python interpreter's module search path.
#define	REPY_REGISTER_SUBINTERPRETER(subinterp_identifier)
	Use this macro at the global level of a C file to initialize a subinterpreter on startup.
#define	REPY_EXTERN_SUBINTERPRETER(subinterp_identifier)
	Macro used to extern in a subinterpreter index variable.
#define	REPY_EXTERN_INCBIN(identifier)
	Macro that creates extern statements for data included by REPY_INCBIN and REPY_INCBIN_TEXT.
#define	REPY_INCBIN(identifier, filename)
	General INCBIN macro used by several other initialization macros to include external Python code.
#define	REPY_INCBIN_TEXT(identifier, filename)
	General INCBIN macro used by several other initialization macros to include external Python code.
#define	REPY_GLOBAL_COMPILE_CACHE(interpreter_index, bytecode_identifier, code_mode, code_str)
	On startup, compiles a Python code string into bytecode with a global handle. Use outside of any functions.
#define	REPY_STATIC_COMPILE_CACHE(interpreter_index, bytecode_identifier, code_mode, code_str)
	On startup, compiles a Python code string into bytecode with a static handle. Use outside of any functions.
#define	REPY_GLOBAL_COMPILE_INCBIN_CACHE(interpreter_index, bytecode_identifier, filename)
	On startup, compiles a INCBINed Python code file into bytecode with a global handle.
#define	REPY_STATIC_COMPILE_INCBIN_CACHE(interpreter_index, bytecode_identifier, filename)
	On startup, compiles a INCBINed Python code file into bytecode with a global handle. Use outside of any functions.

Detailed Description

Macros that initialize REPY resources before or during REPY's initialization process.

Macro Definition Documentation

REPY_ADD_NRM_TO_MAIN_INTERPRETER

#define REPY_ADD_NRM_TO_MAIN_INTERPRETER

Value:

REPY_ON_CONFIG_INTERPRETERS void __repy_config_main_interpreter() { \
    recomp_printf("Configuring Main Interpreter (Index %i)\n", 0); \
    REPY_PushInterpreter(subinterp_identifier); \
    REPY_AddNrmToSysPath(); \
    REPY_PopInterpreter(); \
}

Adds this .nrm file to the main Python interpreter's module search path.

This will allow you to add Python modules (both single files and module folders) to your mod by including them under the additional_files section of your mod.toml. See Including Python Modules for more information.

These modules will be available during REPY_ON_CONFIG_INTERPRETERS.

REPY_EXTERN_INCBIN

#define REPY_EXTERN_INCBIN

(

identifier

)

Value:

extern REPY_u8 identifier[]; \
extern REPY_u8 identifier##_end[]

Macro that creates extern statements for data included by REPY_INCBIN and REPY_INCBIN_TEXT.

See those macros for more information.

REPY_EXTERN_SUBINTERPRETER

#define REPY_EXTERN_SUBINTERPRETER

(

subinterp_identifier

)

Value:

extern REPY_InterpreterIndex subinterp_identifier; \

Macro used to extern in a subinterpreter index variable.

An alternative to extern REPY_InterpreterIndex subinterp_identifier. Potentially more readable.

REPY_GLOBAL_COMPILE_CACHE

#define REPY_GLOBAL_COMPILE_CACHE	(		interpreter_index,
			bytecode_identifier,
			code_mode,
			code_str )

Value:

REPY_Handle bytecode_identifier = 0; \
REPY_ON_INIT_CODE_CACHE void _cache_code_ ## bytecode_identifier () { \
    if (bytecode_identifier == 0) { \
        REPY_PushInterpreter(interpreter_index); \
        char* iden_str = REPY_InlineCodeSourceStrHelper("REPY_GLOBAL_COMPILE_CACHE", __FILE_NAME__, (char*) __func__, __LINE__, #bytecode_identifier); \
        bytecode_identifier = REPY_CompileCStr(code_str, (const char*)iden_str, code_mode); \
        recomp_free(iden_str); \
        REPY_PopInterpreter(); \
    } \
}

On startup, compiles a Python code string into bytecode with a global handle. Use outside of any functions.

To access the the bytecode from another source file, use extern REPY_Handle bytecode_identifier;, where bytecode_identifier is the variable name you entered in the bytecode_identifier parameter.

Parameters

interpreter_index	The index for which interpreter should cache this code. Should be a REPY_InterpreterIndex.
bytecode_identifier	The variable name for the resultant REPY_Handle bytecode handle.
code_mode	The type of code being compiled. See REPY_CodeMode for valid modes.
code_str	The Python code string to compile. Must be NULL-terminated.

REPY_GLOBAL_COMPILE_INCBIN_CACHE

#define REPY_GLOBAL_COMPILE_INCBIN_CACHE	(		interpreter_index,
			bytecode_identifier,
			filename )

Value:

REPY_INCBIN(bytecode_identifier ## _code_str, filename); \
REPY_Handle bytecode_identifier = 0; \
REPY_ON_INIT_CODE_CACHE void _cache_code_ ## bytecode_identifier () { \
    if (bytecode_identifier == 0) { \
        REPY_PushInterpreter(interpreter_index); \
        char* iden_str = REPY_InlineCodeSourceStrHelper("REPY_GLOBAL_COMPILE_INCBIN_CACHE: " filename, __FILE_NAME__, (char*) __func__, __LINE__, #bytecode_identifier); \
        bytecode_identifier = REPY_CompileCStrN((const char*)bytecode_identifier ## _code_str, bytecode_identifier ## _code_str_end - bytecode_identifier ## _code_str, \
            (const char*)iden_str, REPY_CODE_EXEC); \
        recomp_free(iden_str); \
        REPY_PopInterpreter(); \
    } \
}

On startup, compiles a INCBINed Python code file into bytecode with a global handle.

To access the the bytecode from another source file, use extern REPY_Handle bytecode_identifier;, where bytecode_identifier is the variable name you entered in the bytecode_identifier parameter.

Unlike REPY_GLOBAL_COMPILE_CACHE, this macro assumes a REPY_CodeMode of REPY_CODE_EXEC.

Parameters

interpreter_index	The index for which interpreter should cache this code. Should be a REPY_InterpreterIndex.
bytecode_identifier	The variable name for the resultant REPY_Handle bytecode handle.
filename	The path to the module file to INCBIN. The file needs to be in your include path.

REPY_INCBIN

#define REPY_INCBIN	(		identifier,
			filename )

Value:

asm(".pushsection .rodata\n"                      \
    "\t.globl " #identifier "\n"                  \
    "\t.type " #identifier ", @object\n"          \
    "\t.balign 8\n"                               \
    #identifier ":\n"                             \
    "\t.incbin \"" filename "\"\n"                \
    "\t.globl " #identifier "_end\n"              \
    #identifier "_end:\n"                         \
    "\t.popsection\n");                           \
    REPY_EXTERN_INCBIN(identifier)

General INCBIN macro used by several other initialization macros to include external Python code.

The data included by this macro is not NULL-terminated. You'll need to use identifier_end to find the end of the code-block and use identifier_end - identifier to find the length.

Parameters

identifier	The variable name for the start of the data. identifier_end will indicate the end of the data.
filename	The path to the included file. The file needs to be in your include path.

REPY_INCBIN_TEXT

#define REPY_INCBIN_TEXT	(		identifier,
			filename )

Value:

asm(".pushsection .rodata\n"                      \
    "\t.globl " #identifier "\n"                  \
    "\t.type " #identifier ", @object\n"          \
    "\t.balign 8\n"                               \
    #identifier ":\n"                             \
    "\t.incbin \"" filename "\"\n"                \
    "\t.space 1"                                  \
    "\t.globl " #identifier "_end\n"              \
    #identifier "_end:\n"                         \
    "\t.popsection\n");                           \
    REPY_EXTERN_INCBIN(identifier)

General INCBIN macro used by several other initialization macros to include external Python code.

The data included by this macro is NULL-terminated, with identifier_end pointing to the termination character. Therefore, you'll need to use identifier_end - identifier - 1 to find the length of the text.

Parameters

identifier	the variable name for the start of the data. identifier_end will indicate the end of the data.
filename	the path to the included file. The file needs to be in your include path.

REPY_PREINIT_ADD_NRM_TO_ALL_INTERPRETERS

#define REPY_PREINIT_ADD_NRM_TO_ALL_INTERPRETERS

Value:

REPY_ON_PRE_INIT void _repy_register_nrm () { \
    const unsigned char* nrm_file_path = recomp_get_mod_file_path(); \
    REPY_PreInitAddSysPath(nrm_file_path); \
    recomp_free((void*)nrm_file_path); \
};

Adds this .nrm file to Python's module search path.

This will allow you to add Python modules (both single files and module folders) to your mod by including them under the additional_files section of your mod.toml. See Including Python Modules for more information.

These modules will be available by the time REPY_ON_CONFIG_INTERPRETERS runs, and will be available to all subinterpreters. Unless you're creating a mod that bundles Python packages for other mods to use, this is likely not the behavior you want.

REPY_REGISTER_SUBINTERPRETER

#define REPY_REGISTER_SUBINTERPRETER

(

subinterp_identifier

)

Value:

REPY_InterpreterIndex subinterp_identifier = 0; \
REPY_ON_PRE_INIT void __repy_config_ ## subinterp_identifier () { \
    subinterp_identifier = REPY_PreInitRegisterSubinterpreter(); \
    recomp_printf("Registering Subinterpreter '%s' (Index %i)\n", #subinterp_identifier, subinterp_identifier); \
} \
REPY_ON_CONFIG_INTERPRETERS void subinterp_identifier ## _config() { \
    recomp_printf("Configuring Subinterpreter '%s' (Index %i)\n", #subinterp_identifier, subinterp_identifier); \
    REPY_PushInterpreter(subinterp_identifier); \
    REPY_AddNrmToSysPath(); \
    REPY_PopInterpreter(); \
} \

Use this macro at the global level of a C file to initialize a subinterpreter on startup.

The index of the subinterpreter will be stored in a global REPY_InterpreterIndex variable, the name for which is set via the subinterp_identifier argument.

This macro also adds this .nrm to the import pathsys.path for the new subinterpreter, meaning that the subinterpreter can import Python modules stored within the .nrm. See Including Python Modules for more information.

REPY_STATIC_COMPILE_CACHE

#define REPY_STATIC_COMPILE_CACHE	(		interpreter_index,
			bytecode_identifier,
			code_mode,
			code_str )

Value:

static REPY_Handle bytecode_identifier = 0; \
REPY_ON_INIT_CODE_CACHE void _cache_code_ ## bytecode_identifier () { \
    if (bytecode_identifier == 0) { \
        REPY_PushInterpreter(interpreter_index); \
        char* iden_str = REPY_InlineCodeSourceStrHelper("REPY_STATIC_COMPILE_CACHE", __FILE_NAME__, (char*) __func__, __LINE__, #bytecode_identifier); \
        bytecode_identifier = REPY_CompileCStr(code_str, (const char*)iden_str, code_mode); \
        recomp_free(iden_str); \
        REPY_PopInterpreter(); \
    } \
}

On startup, compiles a Python code string into bytecode with a static handle. Use outside of any functions.

Because the REPY_Handle variable is marked as static, there will be no accessing it from other source files.

Parameters

interpreter_index	The index for which interpreter should cache this code. Should be a REPY_InterpreterIndex.
bytecode_identifier	The variable name for the resultant static REPY_Handle bytecode handle.
code_mode	The type of code being compiled. See REPY_CodeMode for valid modes.
code_str	The Python code string to compile. Must be NULL-terminated.

REPY_STATIC_COMPILE_INCBIN_CACHE

#define REPY_STATIC_COMPILE_INCBIN_CACHE	(		interpreter_index,
			bytecode_identifier,
			filename )

Value:

REPY_INCBIN(bytecode_identifier ## _code_str, filename); \
REPY_Handle bytecode_identifier = 0; \
REPY_ON_INIT_CODE_CACHE void _cache_code_ ## bytecode_identifier () { \
    REPY_PushInterpreter(interpreter_index); \
    if (bytecode_identifier == 0) { \
        char* iden_str = REPY_InlineCodeSourceStrHelper("REPY_STATIC_COMPILE_INCBIN_CACHE: " filename, __FILE_NAME__, (char*) __func__, __LINE__, #bytecode_identifier); \
        bytecode_identifier = REPY_CompileCStrN((const char*)bytecode_identifier ## _code_str, bytecode_identifier ## _code_str_end - bytecode_identifier ## _code_str, \
            (const char*)iden_str, REPY_CODE_EXEC); \
        recomp_free(iden_str); \
        REPY_PopInterpreter(); \
    } \
}

On startup, compiles a INCBINed Python code file into bytecode with a global handle. Use outside of any functions.

Because the REPY_Handle variable is marked as static, there will be no accessing it from other source files.

Unlike REPY_GLOBAL_COMPILE_CACHE, this macro assumes a REPY_CodeMode of REPY_CODE_EXEC.

Parameters

interpreter_index	The index for which interpreter should cache this code. Should be a REPY_InterpreterIndex.
bytecode_identifier	The variable name for the resultant static REPY_Handle bytecode handle.
filename	The path to the module file to INCBIN. The file needs to be in your include path.