1. Rui Figueira
  2. clCodegen

Overview

clCodegen v0.1.0 pre-release, Code generation tool from a clReflect database


Note

Everything is still subject to change as I improve clCodegen for my own needs, so these instructions apply mostly to the binaries you can get in the Downloads section, and should not be taken word by word if you're building from source. At this point clCodegen it's pretty much a prototype. I'm mostly focused on what it can do, not how it's coded, so the code is indeed messy with bits and pieces copied from other projects I have. Once I'm happy with the functionality, I'll refactor it, hopefully.

Installation Instructions

Easiest way is to download the zipped package from https://bitbucket.org/ruifig/clcodegen/downloads . It includes everything you need (including clReflect binaries and API)

If you prefer to build it on your own, you'll need Visual Studio 2012. Load the /VisualStudio/clCodeGen.sln solution, and build it. The run /MakeRelease.bat . It will copy everything you need to /release.

The executables in the /release/bin directory can be run directly but require the MSVC 2010 x86 redistributables for clReflect, and MSVC 2012 x86 Update 1 redistributables for clCodegen

Quick Tour

clCodegen is a tool to generate code (or any text for that matter) from a clReflect's database. It can be used to for example generate cross-platform C++ reflection, or to just improve something on top of your use of clReflect. Code generation is done by exposing a clReflect database to a Squirrel script The API exposed is pretty much the clReflect's API, with some minor changes to work around some problems related to the script bindings.

Basic way to use...

clcodegen.exe database.cppbin yourscript.nut output.cpp

The above example will load the specified database (database.cppbin), and run the script (yourscript.nut), which in turn will write to the 'utput.cpp' file.

Some Squirrel notes

  • For convenience, Squirrels documention is included in the /squirrel3 folder. You can get Squirrel's source code at the official website

Other than clReflect API and the standard Squirrel functions, the following functions are also available:

  • print(x) - prints x to the standard output
  • error(x) - prints x to the standard error output
  • incrementIndent() and decrementIndent() - change the current output indentation level. Check /tests/script.nut for examples
  • out(x) - outputs 1 or more lines of text to the specified output file, taking into account the current indentation level

Example

out( "class " + obj.name.text + "{" );
incrementIndent();
... more calls to "out" to output the class's fields, methods, etc
decrementIndent();
out( "};" );
  • getprocessdir() - returns the clcodegen.exe directory. This is useful if you want to put scripts in there (or relative to clcodegen.exe directory) to share between projects.

Example

dofile(getprocessdir() + "/clcodegen_utils.nut", true);
  • getcwd - returns the current working directory

A working example

There is a fully working example inside directory \tests. Run the testall.bat batch file. It will generate a database from gentest1.cpp, and create output.h using the script script.nut.

Contents of output.h will be a close match to the original code, which in itself are of no use at all. It just serves as tutorial and example how to inspect the database.

Two script files are provided

  • \bin\clcodegen_utils.nut Contains generic utility functions you can use in your own scripts.
  • script.nut Contains code to iterate over an entire database, and output C++ code as close as possible to the database, just for testing.

Known limitations

  • clReflect can't handle pointer references, and will just skip any functions using those.

Example

// clReflect can't handle this, so we can skip it with the "noreflect" attribute.
void clcpp_attr(noreflect) someFunction(int*& ptrref)

Deviations from clReflect's API, due to script binding problems

  • Instead of exposing everything inside a "clcpp" namespace, it just exposes everything in Squirrel's global scope.
  • clcpp::Field::type renamed to clcpp::Field::fieldtype, since Squirrel has a keyword "type"
  • clcpp::CArray<T> elements are accessed with the "At" method. example: someclass.fields.At(0); // Access first field
  • Some more deviations that maybe I forgot to mention. Any problems, check script.nut and clcodegen_utils.nut for examples, and let me know if I missed something

Release notes

Main changes not in the pre-compiled binaries yet (from recent to older)

  • Added "expandPath(string)" function
  • Added a function "calchash(string)".
  • Exposed a "Guid" class to the scripts, which allows creation of GUIDs.
  • If any calls to "error" squirrel function are made, the script will be considered as failed.
  • "error" squirrel function now outputs to stdout, instead of stderr, since Visual Studio Build output window was not showing that output.
  • Added a few output methods variations to OutputFile (wr,iw,wi,dw,wd), so make it easier to indent and align code
  • If a script file name is specified without directory, and is not found in the current directory, clcodegen will look for it in the process's directory. This makes it easier to reuse scripts. Just put then in the bin folder.
  • ./tests/script.nut renamed to testdatabase.nut, and moved to the bin folder, so it can be easily reused by other people.
  • ./tests/testall.bat renamed to ./tests/testdatabase.bat
  • Exposed a simple OutputFile class to make it easier to create output file.
  • No more 1-1 relationship between calls to clCodegen and generated files. The script can now accept parameters from clCodegen, and generate any files it wants. Parameters passed to the script are exposed in the global string variable scriptargs
  • Added script utility function hasAttribute
  • Added script utility function findAttribute
  • \bin\clcodegen_utils.nut is now in the bin folder
  • Added script function getprocessdir
  • Added script function getcwd

13.02.2013.0.1.0

  • Initial version