alib::camp::DevtimeResourceCompiler Class Reference

Description:

Manages the compilation of externalized resources from .alibrc files into C++ source code.

This class provides a development-time mechanism to:

1. Parse human-readable .alibrc resource files
2. Register the resources in a ALib Camp's resource pool
3. Generate C++ source code that hard-codes the resources for production builds

This class operates only when the configuration macro ALIB_CAMP_RESOURCE_COMPILATION is set. Otherwise, the class is an almost empty stub. This approach allows a two-phase workflow:

Development Phase:

• Resources are defined in editable .alibrc text files
• The compiler parses these files at program startup
• Generated C++ code is written to designated source files
• Changes to resources are immediately reflected

Production Phase:

• The symbol ALIB_CAMP_RESOURCE_COMPILATION is unset
• Resources are loaded from the generated C++ code
• No file I/O or parsing occurs at runtime
• The .alibrc files are not needed for distribution

The compiler uses file modification timestamps to determine when re-compilation is needed. If the target C++ file is newer than the .alibrc file (with 10ms tolerance), no action is taken.

See also

• Method Do for the main entry point.
• File App/sample.cpp for a complete usage example.
• Chapter 4. Resource Compilation of the Programmer's Manual of module ALib Camp.

Definition at line 201 of file resourcecompiler.hpp.

#include <resourcecompiler.hpp>

Collaboration diagram for alib::camp::DevtimeResourceCompiler:

Public Method Index:
	~DevtimeResourceCompiler ()
	Destructor. This is empty if the symbol ALIB_CAMP_RESOURCE_COMPILATION is not set.
bool	Do (const NString &alibrcFileName, const NString &callingFile, Camp &campInstance, const NString &resourceCategory, bool allowReplacements, const NString &cppFileName)

Protected Field Index:
MonoAllocator *	ma =nullptr

Field Details:

ma

MonoAllocator* alib::camp::DevtimeResourceCompiler::ma =nullptr

protected

The allocator to use. Created only in case resources are to be compiled (and a C++ file is to be patched).

Definition at line 206 of file resourcecompiler.hpp.

Constructor(s) / Destructor Details:

~DevtimeResourceCompiler()

alib::camp::DevtimeResourceCompiler::~DevtimeResourceCompiler ( )

inline

Destructor. This is empty if the symbol ALIB_CAMP_RESOURCE_COMPILATION is not set.

Definition at line 212 of file resourcecompiler.hpp.

Method Details:

Do()

bool alib::camp::DevtimeResourceCompiler::Do	(	const NString &	alibrcFileName,
		const NString &	callingFile,
		Camp &	campInstance,
		const NString &	resourceCategory,
		bool	allowReplacements,
		const NString &	cppFileName )

Main entry point for resource compilation.

This method performs the complete resource compilation workflow:

1. Resolves file paths (relative paths are resolved against CallingFile's directory)
2. Checks file modification timestamps to avoid unnecessary recompilation
3. Parses the .alibrc resource file
4. Registers all resources in the given camp's resource pool
5. Generates C++ code and patches the target source file

File Path Resolution:

• Both AlibrcFileName and CppFileName may be relative or absolute paths
• Relative paths are resolved against the directory containing CallingFile
• Typically, pass FILE as CallingFile to resolve relative to the calling source

Timestamp-Based Compilation:

• Compares modification times of .alibrc and .cpp files
• If the C++ file is newer (with 10ms tolerance), no action is taken
• Returns false to indicate no compilation occurred

Target File Requirements: The C++ file specified by CppFileName must contain two marker comments:

// ALIB-RESOURCE-COMPILER-REPLACEMENT-START
... generated code will replace this section ...
// ALIB-RESOURCE-COMPILER-REPLACEMENT-END

All lines between these markers are replaced with generated resource loading code. The markers themselves are preserved.

Conditional Compilation: When ALIB_CAMP_RESOURCE_COMPILATION is not set, this method becomes a no-op and always returns false.

Example Usage:

void Sample::onBsPrepareConfig() {
    // call parent's implementation. This bulk-loads the resources into the camps.
    App::onBsPrepareConfig();
 
    // now, we just add the resources that parent App did not define for us.
    camp::DevtimeResourceCompiler rc;
    if(!rc.Do( "sample.alibrc", __FILE__, APP, APP.ResourceCategory, true,
                        //       __FILE__ )
                                nullptr )
        )
        bulkloadResources();
 
    enumrecords::bootstrap::Bootstrap<DateCommands  >();
    enumrecords::bootstrap::Bootstrap<DateParameters>();
    enumrecords::bootstrap::Bootstrap<DateOptions   >();
    enumrecords::bootstrap::Bootstrap<DateExitCodes >();
 
    // Read copyright string from resources and format to current version and year
    Paragraphs buffer;
    buffer.LineWidth= 70;
    {ALIB_LOCK_RECURSIVE_WITH(Formatter::DEFAULT_LOCK)
    buffer.AddMarked( APP.GetResource( "AppInfo" ),
                      alib::VERSION,
                      alib::REVISION,
                      CalendarDateTime(DateTime()).Year      );
    }
    cli.AppInfo.Allocate(cli.GetAllocator(), buffer.Buffer);
}

For the corresponding .alibrc file format, see manual section 4.2 The .alibrc File Format..
For the generated output, see the replacement section in App/sample.cpp.

Parameters

alibrcFileName	Path to the input .alibrc resource file.
callingFile	Reference file for resolving relative paths (typically FILE).
campInstance	The ALib Camp instance whose resource pool receives the resources.
resourceCategory	The resource category name for registering resources.
allowReplacements	Determines whether overriding existing resource-keys should raise an ALib Assertion.
cppFileName	Path to the target C++ source file to be patched. If an empty string is given, then the resource file will be loaded in any case and resources will be added.

Returns

true if resources were compiled and the C++ file was updated successfully, false if compilation was skipped (file already up-to-date), an error occurred, or ALIB_CAMP_RESOURCE_COMPILATION is not set.

---

The documentation for this class was generated from the following file:

• resourcecompiler.hpp