Code::Blocks - User contributions [en]

Script bindings

2011-12-13T04:38:52Z

Beldaz:

[[Category:Scripting Code::Blocks]]
Code::Blocks already has exposed a very large chunk of its SDK and wxWidgets stuff to scripts (see [[Scripting commands]]). How is the scripting binding done in C::B? What is required to do to add additional script binding of parts not (yet) exposed? This page is intended to clarify this question and help developers to add additional script bindings to C::B at source-code level. Using [http://wiki.squirrel-lang.org/default.aspx/SquirrelWiki/SqPlus.html SqPlus], it's easy to bind most classes/functions. Readers might hopefully pick this up pretty fast.

Basically, a look at the '''sdk/scripting/bindings/sc_*.cpp''' files will give a good overview (starting with the smaller files). '''sc_progress.cpp''' is the simplest and easiest to read basically. It binds only one method without parameters (and the ctor, of course). It is used in several of the examples below.

Bindings are kept separated in logical units as: '''sc_consts''', '''sc_globals''', '''sc_wxtypes''', etc. So before binding something, think carefully where it belongs to (or needs a new unit).

All the '''sc_*''' files have a "Register_XXX()" function that actually does the bindings. If a new '''sc_*''' file is created, this "Register" function has to be declared as "extern" in '''scriptbindings.cpp''' and also needs to be called from there too. Looking at the other "Register_" functions in '''scriptbindings.cpp''' should make that clear. So to e.g. use '''sc_util_dialogs.cpp''', it has to be declared as "extern void" in '''scriptbindings.cpp''' and called in "RegisterBindings".

== Adding a class ==

To create a script binding for the C++ class "ClassName" you need to call
<pre>
SqPlus::SQClassDef<ClassName>("ScriptClassName")
</pre>
Usually the same name for scripts is used as for the C++ side so "ClassName" in C++ is also bound as "ClassName" in scripts, e.g. <pre>SqPlus::SQClassDef<wxString>("wxString")</pre>

For a class to work correctly within a script it must also be declared in '''sc_base_types.h''', using the format:
<pre>
DECLARE_INSTANCE_TYPE(ClassName)
</pre>
If you don't do this, any functions that are meant to return on object of your new class will be of type "USERPOINTER" rather than "INSTANCE", and squirrel won't know that the class members belong to it. Hence in the script console you might see errors of the form

AN ERROR HAS OCCURED [the index 'ClassMember' does not exist]
CALLSTACK
*FUNCTION [GetModuleMenu()] C:\codeblocks\share\CodeBlocks\scripts\myscript.script line [35]
LOCALS
[myobject] USERPOINTER
[data] INSTANCE
[who] 2
[this] INSTANCE

Here the local variable "myobject" in the plugin script "myscript.script" was supposed to be an object, and its method "ClassMember" was called. However, the object type was not known (see the "[myobject] USERPOINTER" line in the list of locals - it should have been "[myobject] INSTANCE"), and so the call to myobject.ClassMember() was not recognized.

=== Class members ===

To bind member functions/variables the class methods of the SqClassDef class
is used. The easiest of all is "func" which binds a member function, e.g.,

<pre>
SqPlus::SQClassDef<ProgressDialog>("ProgressDialog").
emptyCtor().
func(&ProgressDialog::Update, "Update");
</pre>

As you can see, you can chain these methods together.

The '''emptyCtor()''' is a C::B patch on SqPlus to manually add an empty (script) constructor for the object. Without this, this type of object can't be created in scripts. It would only be possible to get it as a return value of a function call or something. The '''func''' member binds the '''ProgressDialog::Update''' member function as "Update" member function on the script object. So, it's just a one-on-one binding and that's the easiest binding case.

''NOTE:'' Not all bindings should have an '''emptyCtor()'''. For example, scripts should not have the ability to create, say, a new "cbProject". Instead, it should go through the standard route: '''GetProjectManager().NewProject()'''. Another thing to note about '''emptyCtor()''' is that it imposes certain requirements on the C++ class, like that your C++ object ''must'' have a public copy constructor (but this is a requirement anyway). Look for an example in all basic classes (e.g., cbEditor). Copy constructors have been added to them which do nothing, just throw an error. They are not used by scripting (SqPlus has been patched for this) but they must exist nevertheless. Anyway, these are some
"advanced" scripting issues which will become clearer once the basics are more clear. All of the wxWidgets GUI controls have private copy-ctors btw.

=== Function arguments ===

In order to be able to use a registered type as a function's argument, this type must be declared in '''sc_base_types.h'''. It's pretty easy, just a macro. If the function to register will not be used as a function's parameter (or return value), then there is no need for that. So it's the '''DECLARE_INSTANCE_TYPE''' and '''DECLARE_ENUM_TYPE''' macro, depending on what shall be registered.

=== Constructors with arguments ===

This next example comes from '''sc_util_dialogs.cpp''':
<pre>
SqPlus::SQClassDef<EditPathDlg>("EditPathDlg").
staticFuncVarArgs(&EditPathDlg_Ctor, "constructor", "*").
[...]
</pre>

The second line might look complex but it's really not. "staticFuncVarArgs" binds a squirrel C function to script (with variable arguments, as the name suggests). The first parameter is the C function name, the second is the function's name in scripts. For constructors it is always "constructor". The third parameter is a string saying what parameters this function accepts. "*" means anything and is used with "staticFuncVarArgs".

''NOTE:'' If, instead of "*", the parameter string had been something like "nnsn", it would mean this function takes ([n]umber, [n]umber, [s]tring, [n]umber) parameters. Clever and with automatic type matching (means if types do not match a script exception is raised). In C::B that form isn't used - "*" is always used. Because, for example, "string" is not the same as wxString that is constantly used. Anyway, it's not being used.

In the example '''staticFuncVarArgs(&EditPathDlg_Ctor, "constructor", "*")''' defines the custom ctor. Custom ctors must be bound to a squirrel callback which have the signature '''SQInteger FuncName(HSQUIRRELVM v)''', so in this case the callback is '''SQInteger EditPathDlg_Ctor(HSQUIRRELVM v)'''.

In the C function that will act as the constructor all that needs to be done is to access the parameters and construct the object manually, using SqPlus methods to do it. When a script calls a function and it lands in a C function (like the one used above) it passes all arguments onto the stack (including "this" object, in case of global functions, "this" is the VM). Anyway, to read a function parameter squirrel gives the value at the appropriate place on the stack. Think of it as an array of parameters. So to read parameter three, ask for the value on the fourth place on the stack (remember that parameter 1 is "this", so the second function parameter is at index 3). The "0" as first parameter in some functions is the NULL pointer for the wxWidgets parent (if required). "this" is never used because "this" is handled by SqPlus to call the member function on the correct object.

Usually we only care about the actual parameters. "StackHandler" is a helper class to make it easy to access the stack. It has functions to get/set values on the stack like: "GetInt()", "GetBool()", etc. They all take the index as parameter. You can see this being used in '''SQInteger EditPairDlg_Ctor(HSQUIRRELVM v)''' within '''sc_util_dialogs.cpp'''.

Also worth mentioning in the same function is this construct:
<pre>
*SqPlus::GetInstance<wxString>(v, 2)
</pre>
It gets access to an object address, not a primitive type. This actually returns the wxString object at stack index 2 because StackHandler is not aware of any types that is self-bound. It can't use it so the '''SqPlus::GetInstance''' helper function has to be used. The template parameter tells what type is there. The first parameter is the squirrel VM and the last parameter is the stack index. '''SqPlus::GetInstance''' always returns a pointer to the object, so it's dereferenced using (*) to access the actual object.

All what's left for this section is '''SqPlus::PostConstruct'''. This is done to inform SqPlus about the new object. This will actually bind, e.g., the new EditPathDlg object that has been created to the script. Without it, just the object would be created in the C++ side. But a script is expecting to access that object - that function does that. It is provided with the dtor method because when Squirrel decides that this object needs to be garbage-collected, it calls a callback function to do this. It's a boilerplate function, nothing to it, really.

=== Other bindings ===

The "staticFunc" is the same but a "static C function". There is "var()" left but I guess this is clear by now: It's for public member variables.

== Overloaded Functions ==

All "SqClassDef" member functions (like "func") are actually template functions of style '''func(&foo:bar, "bar")'''. Suppose '''void foo::bar(int)''' ''and'' '''void foo::bar(float)''' are two overloads of the same function in C++ side. Trying to use the '''func(&foo:bar, "bar")''' binding will fail miserably because the compiler doesn't know which one to bind. In that case, "func" must be told which overload is the one to be used. This is done using a typedef. Assuming the usage of the (float) overload, here is what you do:

<pre>
typedef void(*FOOBAR_FLOAT)(float);
func<FOOBAR_FLOAT>(&foo::bar, "bar");
</pre>

== Final words ==

Just remember one thing: Strive for simplicity! If you start on wx bindings, there is no need for every enum or function param that is used. Only add what's really required... not everything. This means e.g. for the wx control ctors, just what is necessary, as a matter of fact, no constructor for wx controls.

== Links ==
[http://wiki.squirrel-lang.org/default.aspx/SquirrelWiki/SqPlus.html Sq Plus page on Squirrel wiki]

[http://wiki.squirrel-lang.org/default.aspx/SquirrelWiki/SqPlusFAQ.html Sq Plus FAQ]

[[Scripting commands]] lists the current script bindings to date.

Script bindings

2011-12-12T08:45:50Z

Beldaz: Added link to list of current script bindings.

[[Category:Scripting Code::Blocks]]
Code::Blocks already has exposed a very large chunk of its SDK and wxWidgets stuff to scripts (see [[Scripting commands]]). How is the scripting binding done in C::B? What is required to do to add additional script binding of parts not (yet) exposed? This page is intended to clarify this question and help developers to add additional script bindings to C::B at source-code level. Using [http://wiki.squirrel-lang.org/default.aspx/SquirrelWiki/SqPlus.html SqPlus], it's easy to bind most classes/functions. Readers might hopefully pick this up pretty fast.

Basically, a look at the '''sdk/scripting/bindings/sc_*.cpp''' files will give a good overview (starting with the smaller files). '''sc_progress.cpp''' is the simplest and easiest to read basically. It binds only one method without parameters (and the ctor, of course). It is used in several of the examples below.

Bindings are kept separated in logical units as: '''sc_consts''', '''sc_globals''', '''sc_wxtypes''', etc. So before binding something, think carefully where it belongs to (or needs a new unit).

All the '''sc_*''' files have a "Register_XXX()" function that actually does the bindings. If a new '''sc_*''' file is created, this "Register" function has to be declared as "extern" in '''scriptbindings.cpp''' and also needs to be called from there too. Looking at the other "Register_" functions in '''scriptbindings.cpp''' should make that clear. So to e.g. use '''sc_util_dialogs.cpp''', it has to be declared as "extern void" in '''scriptbindings.cpp''' and called in "RegisterBindings".

== Adding a class ==

To create a script binding for the C++ class "ClassName" you need to call
<pre>
SqPlus::SQClassDef<ClassName>("ScriptClassName")
</pre>
Usually the same name for scripts is used as for the C++ side so "ClassName" in C++ is also bound as "ClassName" in scripts, e.g. <pre>SqPlus::SQClassDef<wxString>("wxString")</pre>

=== Class members ===

To bind member functions/variables the class methods of the SqClassDef class
is used. The easiest of all is "func" which binds a member function, e.g.,

<pre>
SqPlus::SQClassDef<ProgressDialog>("ProgressDialog").
emptyCtor().
func(&ProgressDialog::Update, "Update");
</pre>

As you can see, you can chain these methods together.

The '''emptyCtor()''' is a C::B patch on SqPlus to manually add an empty (script) constructor for the object. Without this, this type of object can't be created in scripts. It would only be possible to get it as a return value of a function call or something. The '''func''' member binds the '''ProgressDialog::Update''' member function as "Update" member function on the script object. So, it's just a one-on-one binding and that's the easiest binding case.

''NOTE:'' Not all bindings should have an '''emptyCtor()'''. For example, scripts should not have the ability to create, say, a new "cbProject". Instead, it should go through the standard route: '''GetProjectManager().NewProject()'''. Another thing to note about '''emptyCtor()''' is that it imposes certain requirements on the C++ class, like that your C++ object ''must'' have a public copy constructor (but this is a requirement anyway). Look for an example in all basic classes (e.g., cbEditor). Copy constructors have been added to them which do nothing, just throw an error. They are not used by scripting (SqPlus has been patched for this) but they must exist nevertheless. Anyway, these are some
"advanced" scripting issues which will become clearer once the basics are more clear. All of the wxWidgets GUI controls have private copy-ctors btw.

=== Function arguments ===

In order to be able to use a registered type as a function's argument, this type must be declared in '''sc_base_types.h'''. It's pretty easy, just a macro. If the function to register will not be used as a function's parameter (or return value), then there is no need for that. So it's the '''DECLARE_INSTANCE_TYPE''' and '''DECLARE_ENUM_TYPE''' macro, depending on what shall be registered.

=== Constructors with arguments ===

This next example comes from '''sc_util_dialogs.cpp''':
<pre>
SqPlus::SQClassDef<EditPathDlg>("EditPathDlg").
staticFuncVarArgs(&EditPathDlg_Ctor, "constructor", "*").
[...]
</pre>

The second line might look complex but it's really not. "staticFuncVarArgs" binds a squirrel C function to script (with variable arguments, as the name suggests). The first parameter is the C function name, the second is the function's name in scripts. For constructors it is always "constructor". The third parameter is a string saying what parameters this function accepts. "*" means anything and is used with "staticFuncVarArgs".

''NOTE:'' If, instead of "*", the parameter string had been something like "nnsn", it would mean this function takes ([n]umber, [n]umber, [s]tring, [n]umber) parameters. Clever and with automatic type matching (means if types do not match a script exception is raised). In C::B that form isn't used - "*" is always used. Because, for example, "string" is not the same as wxString that is constantly used. Anyway, it's not being used.

In the example '''staticFuncVarArgs(&EditPathDlg_Ctor, "constructor", "*")''' defines the custom ctor. Custom ctors must be bound to a squirrel callback which have the signature '''SQInteger FuncName(HSQUIRRELVM v)''', so in this case the callback is '''SQInteger EditPathDlg_Ctor(HSQUIRRELVM v)'''.

In the C function that will act as the constructor all that needs to be done is to access the parameters and construct the object manually, using SqPlus methods to do it. When a script calls a function and it lands in a C function (like the one used above) it passes all arguments onto the stack (including "this" object, in case of global functions, "this" is the VM). Anyway, to read a function parameter squirrel gives the value at the appropriate place on the stack. Think of it as an array of parameters. So to read parameter three, ask for the value on the fourth place on the stack (remember that parameter 1 is "this", so the second function parameter is at index 3). The "0" as first parameter in some functions is the NULL pointer for the wxWidgets parent (if required). "this" is never used because "this" is handled by SqPlus to call the member function on the correct object.

Usually we only care about the actual parameters. "StackHandler" is a helper class to make it easy to access the stack. It has functions to get/set values on the stack like: "GetInt()", "GetBool()", etc. They all take the index as parameter. You can see this being used in '''SQInteger EditPairDlg_Ctor(HSQUIRRELVM v)''' within '''sc_util_dialogs.cpp'''.

Also worth mentioning in the same function is this construct:
<pre>
*SqPlus::GetInstance<wxString>(v, 2)
</pre>
It gets access to an object address, not a primitive type. This actually returns the wxString object at stack index 2 because StackHandler is not aware of any types that is self-bound. It can't use it so the '''SqPlus::GetInstance''' helper function has to be used. The template parameter tells what type is there. The first parameter is the squirrel VM and the last parameter is the stack index. '''SqPlus::GetInstance''' always returns a pointer to the object, so it's dereferenced using (*) to access the actual object.

All what's left for this section is '''SqPlus::PostConstruct'''. This is done to inform SqPlus about the new object. This will actually bind, e.g., the new EditPathDlg object that has been created to the script. Without it, just the object would be created in the C++ side. But a script is expecting to access that object - that function does that. It is provided with the dtor method because when Squirrel decides that this object needs to be garbage-collected, it calls a callback function to do this. It's a boilerplate function, nothing to it, really.

=== Other bindings ===

The "staticFunc" is the same but a "static C function". There is "var()" left but I guess this is clear by now: It's for public member variables.

== Overloaded Functions ==

All "SqClassDef" member functions (like "func") are actually template functions of style '''func(&foo:bar, "bar")'''. Suppose '''void foo::bar(int)''' ''and'' '''void foo::bar(float)''' are two overloads of the same function in C++ side. Trying to use the '''func(&foo:bar, "bar")''' binding will fail miserably because the compiler doesn't know which one to bind. In that case, "func" must be told which overload is the one to be used. This is done using a typedef. Assuming the usage of the (float) overload, here is what you do:

<pre>
typedef void(*FOOBAR_FLOAT)(float);
func<FOOBAR_FLOAT>(&foo::bar, "bar");
</pre>

== Final words ==

Just remember one thing: Strive for simplicity! If you start on wx bindings, there is no need for every enum or function param that is used. Only add what's really required... not everything. This means e.g. for the wx control ctors, just what is necessary, as a matter of fact, no constructor for wx controls.

== Links ==
[http://wiki.squirrel-lang.org/default.aspx/SquirrelWiki/SqPlus.html Sq Plus page on Squirrel wiki]

[http://wiki.squirrel-lang.org/default.aspx/SquirrelWiki/SqPlusFAQ.html Sq Plus FAQ]

[[Scripting commands]] lists the current script bindings to date.

Source hierarchy

2011-12-12T05:35:37Z

Beldaz:

[[Category:Developer Documentation]]

=== Top-level layout ===

The ''src'' folder within the SVN trunk directory [http://svn.berlios.de/wsvn/codeblocks/trunk/src/] contains the following sub-directories:

<pre>
base - ?? source for exchndl.dll, and tinyxml source
build_tools - ?? tools used within build process such as for included SVN revision number (not sure about scrooge)
i18n - i18n (internationalization) support files
include - header files for libcodeblocks, these headers are used by the plugins and the main application
mime - mime-type files, icons and other metadata
plugins - source for C::B plugins
scripts - squirrel script files and associated support files
sdk - cpp files for libcodeblocks, also all the bundled libs have been put here (wxscintilla, wxpropgrid, scripting)
src - header and cpp files for the main executable
templates - files relating to templates for different types of files and projects within C::B
tools - Code for programs other than C::B
</pre>

=== Main Executable ===
The Codeblocks executable is built from ''src/src'', but most of the functionality is contained within libcodeblocks built from ''src/sdk''. The reason for this appears to be the need to avoid unresolved symbols in DLL files - a good explanation for the need for this can be found at [http://edll.sourceforge.net/#sub_dll]

=== Plugins ===
* All plugins go into the ''src/plugins'' folder.
* Contrib and non-core plugins go into ''src/plugins/contrib/''

=== Scripts ===
Resources for writing scripts as found in ''src/scripts'' can be found in [[Scripting Code::Blocks]]

== Links ==
Related forum discussion [/index.php/topic,15657.msg105327.html]

Source hierarchy

2011-12-11T03:18:31Z

Beldaz: Created page with "Category:Developer Documentation The ''src'' within the SVN trunk directory [http://svn.berlios.de/wsvn/codeblocks/trunk/src/] contains the following sub-directories: <pre>..."

[[Category:Developer Documentation]]

The ''src'' within the SVN trunk directory [http://svn.berlios.de/wsvn/codeblocks/trunk/src/] contains the following sub-directories:

<pre>
base - ?? source for exchndl.dll, and tinyxml source
build_tools - ?? tools used within build process such as for included SVN revision number (not sure about scrooge)
i18n - i18n (internationalization) support files
include - header files for libcodeblocks, these headers are used by the plugins and the main application
mime - mime-type files, icons and other metadata
plugins - source for C::B plugins
scripts - squirrel script files and associated support files
sdk - cpp files for libcodeblocks, also all the bundled libs have been put here (wxscintilla, wxpropgrid, scripting)
src - header and cpp files for the main executable
templates - files relating to templates for different types of files and projects within C::B
tools - Code for programs other than C::B
</pre>

=== Plugins ===
* All plugins go into the ''src/plugins'' folder.
* Contrib and non-core plugins go into ''src/plugins/contrib/''

=== Scripts ===
Resources for writing scripts as found in ''src/scripts'' can be found in [[Scripting Code::Blocks]]

Script bindings

2011-12-10T10:42:28Z

Beldaz: Attempted to add some structure to the page and clean up some of the text.

[[Category:Scripting Code::Blocks]]
Code::Blocks already has exposed a very large chunk of its SDK and wxWidgets stuff to scripts. How is the scripting binding done in C::B? What is required to do to add additional script binding of parts not (yet) exposed? This page is intended to clarify this question and help developers to add additional script bindings to C::B at source-code level. Using [http://wiki.squirrel-lang.org/default.aspx/SquirrelWiki/SqPlus.html SqPlus], it's easy to bind most classes/functions. Readers might hopefully pick this up pretty fast.

Basically, a look at the '''sdk/scripting/bindings/sc_*.cpp''' files will give a good overview (starting with the smaller files). '''sc_progress.cpp''' is the simplest and easiest to read basically. It binds only one method without parameters (and the ctor, of course). It is used in several of the examples below.

Bindings are kept separated in logical units as: '''sc_consts''', '''sc_globals''', '''sc_wxtypes''', etc. So before binding something, think carefully where it belongs to (or needs a new unit).

All the '''sc_*''' files have a "Register_XXX()" function that actually does the bindings. If a new '''sc_*''' file is created, this "Register" function has to be declared as "extern" in '''scriptbindings.cpp''' and also needs to be called from there too. Looking at the other "Register_" functions in '''scriptbindings.cpp''' should make that clear. So to e.g. use '''sc_util_dialogs.cpp''', it has to be declared as "extern void" in '''scriptbindings.cpp''' and called in "RegisterBindings".

== Adding a class ==

To create a script binding for the C++ class "ClassName" you need to call
<pre>
SqPlus::SQClassDef<ClassName>("ScriptClassName")
</pre>
Usually the same name for scripts is used as for the C++ side so "ClassName" in C++ is also bound as "ClassName" in scripts, e.g. <pre>SqPlus::SQClassDef<wxString>("wxString")</pre>

=== Class members ===

To bind member functions/variables the class methods of the SqClassDef class
is used. The easiest of all is "func" which binds a member function, e.g.,

<pre>
SqPlus::SQClassDef<ProgressDialog>("ProgressDialog").
emptyCtor().
func(&ProgressDialog::Update, "Update");
</pre>

As you can see, you can chain these methods together.

The '''emptyCtor()''' is a C::B patch on SqPlus to manually add an empty (script) constructor for the object. Without this, this type of object can't be created in scripts. It would only be possible to get it as a return value of a function call or something. The '''func''' member binds the '''ProgressDialog::Update''' member function as "Update" member function on the script object. So, it's just a one-on-one binding and that's the easiest binding case.

''NOTE:'' Not all bindings should have an '''emptyCtor()'''. For example, scripts should not have the ability to create, say, a new "cbProject". Instead, it should go through the standard route: '''GetProjectManager().NewProject()'''. Another thing to note about '''emptyCtor()''' is that it imposes certain requirements on the C++ class, like that your C++ object ''must'' have a public copy constructor (but this is a requirement anyway). Look for an example in all basic classes (e.g., cbEditor). Copy constructors have been added to them which do nothing, just throw an error. They are not used by scripting (SqPlus has been patched for this) but they must exist nevertheless. Anyway, these are some
"advanced" scripting issues which will become clearer once the basics are more clear. All of the wxWidgets GUI controls have private copy-ctors btw.

=== Function arguments ===

In order to be able to use a registered type as a function's argument, this type must be declared in '''sc_base_types.h'''. It's pretty easy, just a macro. If the function to register will not be used as a function's parameter (or return value), then there is no need for that. So it's the '''DECLARE_INSTANCE_TYPE''' and '''DECLARE_ENUM_TYPE''' macro, depending on what shall be registered.

=== Constructors with arguments ===

This next example comes from '''sc_util_dialogs.cpp''':
<pre>
SqPlus::SQClassDef<EditPathDlg>("EditPathDlg").
staticFuncVarArgs(&EditPathDlg_Ctor, "constructor", "*").
[...]
</pre>

The second line might look complex but it's really not. "staticFuncVarArgs" binds a squirrel C function to script (with variable arguments, as the name suggests). The first parameter is the C function name, the second is the function's name in scripts. For constructors it is always "constructor". The third parameter is a string saying what parameters this function accepts. "*" means anything and is used with "staticFuncVarArgs".

''NOTE:'' If, instead of "*", the parameter string had been something like "nnsn", it would mean this function takes ([n]umber, [n]umber, [s]tring, [n]umber) parameters. Clever and with automatic type matching (means if types do not match a script exception is raised). In C::B that form isn't used - "*" is always used. Because, for example, "string" is not the same as wxString that is constantly used. Anyway, it's not being used.

In the example '''staticFuncVarArgs(&EditPathDlg_Ctor, "constructor", "*")''' defines the custom ctor. Custom ctors must be bound to a squirrel callback which have the signature '''SQInteger FuncName(HSQUIRRELVM v)''', so in this case the callback is '''SQInteger EditPathDlg_Ctor(HSQUIRRELVM v)'''.

In the C function that will act as the constructor all that needs to be done is to access the parameters and construct the object manually, using SqPlus methods to do it. When a script calls a function and it lands in a C function (like the one used above) it passes all arguments onto the stack (including "this" object, in case of global functions, "this" is the VM). Anyway, to read a function parameter squirrel gives the value at the appropriate place on the stack. Think of it as an array of parameters. So to read parameter three, ask for the value on the fourth place on the stack (remember that parameter 1 is "this", so the second function parameter is at index 3). The "0" as first parameter in some functions is the NULL pointer for the wxWidgets parent (if required). "this" is never used because "this" is handled by SqPlus to call the member function on the correct object.

Usually we only care about the actual parameters. "StackHandler" is a helper class to make it easy to access the stack. It has functions to get/set values on the stack like: "GetInt()", "GetBool()", etc. They all take the index as parameter. You can see this being used in '''SQInteger EditPairDlg_Ctor(HSQUIRRELVM v)''' within '''sc_util_dialogs.cpp'''.

Also worth mentioning in the same function is this construct:
<pre>
*SqPlus::GetInstance<wxString>(v, 2)
</pre>
It gets access to an object address, not a primitive type. This actually returns the wxString object at stack index 2 because StackHandler is not aware of any types that is self-bound. It can't use it so the '''SqPlus::GetInstance''' helper function has to be used. The template parameter tells what type is there. The first parameter is the squirrel VM and the last parameter is the stack index. '''SqPlus::GetInstance''' always returns a pointer to the object, so it's dereferenced using (*) to access the actual object.

All what's left for this section is '''SqPlus::PostConstruct'''. This is done to inform SqPlus about the new object. This will actually bind, e.g., the new EditPathDlg object that has been created to the script. Without it, just the object would be created in the C++ side. But a script is expecting to access that object - that function does that. It is provided with the dtor method because when Squirrel decides that this object needs to be garbage-collected, it calls a callback function to do this. It's a boilerplate function, nothing to it, really.

=== Other bindings ===

The "staticFunc" is the same but a "static C function". There is "var()" left but I guess this is clear by now: It's for public member variables.

== Overloaded Functions ==

All "SqClassDef" member functions (like "func") are actually template functions of style '''func(&foo:bar, "bar")'''. Suppose '''void foo::bar(int)''' ''and'' '''void foo::bar(float)''' are two overloads of the same function in C++ side. Trying to use the '''func(&foo:bar, "bar")''' binding will fail miserably because the compiler doesn't know which one to bind. In that case, "func" must be told which overload is the one to be used. This is done using a typedef. Assuming the usage of the (float) overload, here is what you do:

<pre>
typedef void(*FOOBAR_FLOAT)(float);
func<FOOBAR_FLOAT>(&foo::bar, "bar");
</pre>

== Final words ==

Just remember one thing: Strive for simplicity! If you start on wx bindings, there is no need for every enum or function param that is used. Only add what's really required... not everything. This means e.g. for the wx control ctors, just what is necessary, as a matter of fact, no constructor for wx controls.

== Links ==
[http://wiki.squirrel-lang.org/default.aspx/SquirrelWiki/SqPlus.html Sq Plus page on Squirrel wiki]

[http://wiki.squirrel-lang.org/default.aspx/SquirrelWiki/SqPlusFAQ.html Sq Plus FAQ]

Script bindings

2011-12-10T09:03:54Z

Beldaz: Added a couple of useful links to SqPlus

[[Category:Scripting Code::Blocks]]
Code::Blocks already has exposed a very large chunk of its SDK and wxWidgets stuff to scripts. Well, but how is the scripting binding done in C::B? What is required to do to add additional script binding of parts not (yet) exposed? This page is intended to clarify this question and help developers to add additional script bindings to C::B at source-code level. Readers might hopefully pick this up pretty fast.

Basically, a look at the '''sdk/scripting/bindings/sc_*.cpp''' files will give a good overview (starting with the smaller files). Using [http://wiki.squirrel-lang.org/default.aspx/SquirrelWiki/SqPlus.html SqPlus], it's easy to bind most classes/functions.

'''SqPlus::SQClassDef<ClassName>("ScriptClassName")''' creates a class script binding for the C++ class "ClassName". Usually the same name for scripts is used as for the C++ side so "ClassName" in C++ is also bound as "ClassName" in scripts, e.g. '''SqPlus::SQClassDef<wxString>("wxString")'''.

To bind member functions/variables the class methods of the SqClassDef class
is used. The easiest of all is "func" which binds a member function, e.g.
SqPlus::SQClassDef<ProgressDialog>("ProgressDialog").
emptyCtor().
func(&ProgressDialog::Update, "Update");
The '''emptyCtor()''' is a C::B patch on SqPlus to manually add an empty (script) constructor for the object. Without this, this type of object can't be created in scripts. It would only be possible to get it as a return value of a function call or something. The '''func''' member binds the '''ProgressDialog::Update''' member function as "Update" member function on the script object. So, it's just a one-on-one binding and that's the easiest binding case.

''NOTE:'' Not all bindings should have an '''emptyCtor()'''. For example, scripts should not have the ability to create, say, a new "cbProject". Instead, it should go through the standard route: '''GetProjectManager().NewProject()'''. Another thing to note about '''emptyCtor()''' is that it imposes certain requirements on the C++ class, like that your C++ object ''must'' have a public copy constructor (but this is a requirement anyway). Look for an example in all basic classes (eg. cbEditor). Copy constructors have been added to them which do nothing, just throw an error. They are not used by scripting (SqPlus has been patched for this) but they must exist nevertheless. Anyway, these are some
"advanced" scripting issues which will become clearer once the basics are more clear. All of the wxWidgets GUI controls have private copy-ctors btw.

One important thing to note: In order to be able to use a registered type as a function's argument, this type must be declared in '''sc_base_types.h'''. It's pretty easy, just a macro. If the function to register will not be used as a function's parameter (or return value), then there is no need for that. So it's the '''DECLARE_INSTANCE_TYPE''' and '''DECLARE_ENUM_TYPE''' macro, depending on what shall be registered.

Bindings are kept separated in logical units as: '''sc_consts''', '''sc_globals''', '''sc_wxtypes''', etc. So before binding something, think carefully where it belongs to (or needs a new unit).

'''sc_progress.cpp''' is the simplest and easiest to read basically. It binds only one method without parameters (and the ctor, of course). Things get more complex only for two situations:

1) constructors with arguments, and
2) overloaded functions

Now we are looking at e.g. '''SqPlus::SQClassDef<EditPathDlg>("EditPathDlg").[...]'''. It might look complex but it's really not. '''staticFuncVarArgs(&EditPathDlg_Ctor, "constructor", "*")''': This is what defines the custom ctor. Custom ctors must be bound to a squirrel callback which have this signature: '''SQInteger FuncName(HSQUIRRELVM v)'''. That's '''SQInteger EditPathDlg_Ctor(HSQUIRRELVM v)'''.

The "staticFuncVarArgs" binds a squirrel C function to script (with variable arguments, as the name suggests). The first parameter is the C function name, the second is the function's name in scripts. For constructors it is always "constructor". The third parameter is a string saying what parameters this function accepts. "*" means anything and
is used with "staticFuncVarArgs".

''NOTE:'' If it was something like "nnsn", it would mean this function takes ([n]umber, [n]umber, [s]tring, [n]umber) parameters. Clever and with automatic type matching (means if types do not match a script exception is raised). In C::B that form isn't used, there always "*" is used. Because, for example, "string" is not the same as wxString that is constantly used. Anyway, it's not being used.

In the C function that will act as the constructor all to do now is to access the parameters and construct the object manually (using SqPlus methods to do it). When a script calls a function and it lands in a C function (like the one used above) it passes all arguments onto the stack (including "this" object, in case of global functions, "this" is the VM). Anyway, to read a function parameter squirrel gives the value at the appropriate place on the stack. Think of it as an array of parameters. So to read parameter three, ask for the value on the fourth place on the stack (remember that parameter 1 is "this", so the second function parameter is at index 3). The "0" as first parameter in some functions is the NULL pointer for the wxWidgets parent (if required). "this" is never used because "this" is handled by SqPlus to call the member function on the correct object.

Usually only the actual parameters are to care about. "StackHandler" is a helper class to make it easy to access the stack. It has functions to get/set values on the stack like: "GetInt()", "GetBool()", etc. They all take the index as parameter.

One thing left is this construct: '''*SqPlus::GetInstance<wxString>(v, 2)'''. It gets access to an object address, not a primitive type. This actually returns the wxString object at stack index 2 because StackHandler is not aware of any types that is self-bound. It can't use it so the '''SqPlus::GetInstance''' helper function has to be used. The template parameter tells what type is there. The first parameter is the squirrel VM and the last parameter is the stack index. '''SqPlus::GetInstance''' always returns a pointer to the object, so it's dereferenced using (*) to access the actual object.

All what's left for this section is '''SqPlus::PostConstruct'''. This is done to inform SqPlus about the new object. This will actually bind e.g. the new EditPathDlg object that has been created to the script. Without it, just the object would be created in the C++ side. But a script is expecting to access that object - that function does that. It is provided with the dtor method because when Squirrel decides that this object needs to be garbage-collected, it calls a callback function to do this. It's a biolerplate function, nothing to it, really.

The "staticFunc" is the same but a "static C function". There is "var()" left but I guess this is clear by now: It's for public member variables.

One more thing to explain: "Function overloads".

All "SqClassDef" member functions (like "func") are actually template functions of style '''func(&foo:bar, "bar")'''. Suppose '''void foo::bar(int)''' ''and'' '''void foo::bar(float)''' are two overloads of the same function in C++ side. Trying to use the '''func(&foo:bar, "bar")''' binding will fail miserably because the compiler doesn't know which one to bind. In that case, "func" mus be told which overload is the one to be used. This is done using a typedef. Assuming the usage of the (float) overload, here is what's to do:

typedef void(*FOOBAR_FLOAT)(float);
func<FOOBAR_FLOAT>(&foo::bar, "bar");

All these '''sc_*''' files, have a "Register_XXX()" function that actually does the bindings. If a new '''sc_*''' file is created, this "Register" function has to be declared as "extern" in '''scriptbindings.cpp''' and also needs to be called from there too. Looking at the other "Register_" functions in '''scriptbindings.cpp''' should make that clear. So to e.g. use '''sc_util_dialogs.cpp''', it has to be declared as "extern void" in '''scriptbindings.cpp''' and called in "RegisterBindings".

Just remember one thing: Strive for simplicity! If you start on wx bindings, there is no need for every enum or function param that is used. Only add what's really required... not everything. This means e.g. for the wx control ctors, just what is necessary, as a matter of fact, no constructor for wx controls.

[http://wiki.squirrel-lang.org/default.aspx/SquirrelWiki/SqPlus.html Sq Plus page on Squirrel wiki]

[http://wiki.squirrel-lang.org/default.aspx/SquirrelWiki/SqPlusFAQ.html Sq Plus FAQ]

Installing Code::Blocks from source on Windows

2011-12-09T05:58:20Z

Beldaz: Added fix for failed linking due to exported inlines

[[Category:Installing Code::Blocks]]
[[Category:Installing Code::Blocks from source]]
== Prerequisites ==

=== Note for RC2 users ===

The older Code::Blocks RC2 does not support global compiler variables which were added after RC2 was released and is unable to read project files generated with post-RC2 versions.
To build Code::Blocks, you need a post-RC2 build, such as ''8.02'' or any of the ''nightly builds'' obtainable by [/index.php?board=20.0 searching the forum].

=== MinGW compiler ===

At the present time, Code::Blocks only compiles successfully with the MinGW compiler (or any other gcc for that matter). You will need a complete, working [[MinGW installation]] or [http://www.tdragon.net/recentgcc/ TDM-MinGW package GCC 4.4.1].

'''Do not''' use the barebones MinGW with GCC 4.5.1 as you'll run (with this specific version) into [http://gcc.gnu.org/bugzilla/show_bug.cgi?id=43601 a linker bug] (which happened to me on Vista SP1 32-bit on 2011-02-28); the solution is to use the TDM-GCC 4.5.1 package.

=== wxWidgets ===

[http://www.wxwidgets.org/ wxWidgets.org]

Code::Blocks uses
* since 28 March 2009 wxWidgets 2.8.10 <br/>Download: [http://prdownloads.sourceforge.net/wxwindows/wxMSW-2.8.10.zip wxMSW-2.8.10.zip]

* since 18 October 2008 wxWidgets 2.8.9 <br/>Download: [http://prdownloads.sourceforge.net/wxwindows/wxMSW-2.8.9.zip wxMSW-2.8.9.zip]

* since 19 July 2008 wxWidgets 2.8.8 <br/>Download: [http://prdownloads.sourceforge.net/wxwindows/wxMSW-2.8.8.zip wxMSW-2.8.8.zip]

* since 28 November 2007 wxWidgets 2.8.7 <br/>Download: [http://prdownloads.sourceforge.net/wxwindows/wxMSW-2.8.7.zip wxMSW-2.8.7.zip]

* since November 2007 wxWidgets 2.8.6 <br/>Download: [http://prdownloads.sourceforge.net/wxwindows/wxMSW-2.8.6.zip wxMSW-2.8.6.zip]

* since May 2007 wxWidgets 2.8.4<br/>Download: [http://prdownloads.sourceforge.net/wxwindows/wxMSW-2.8.4.zip wxMSW-2.8.4.zip]

For latest infos check forum: [/index.php?topic=3299.0 Important changes to the nightly builds]

You do ''not'' need MSYS (''in fact, if you have MSYS, make sure it is not in your PATH when building wxWidgets'').

=== SVN client ===

In order to check out the Code::Blocks sources you will need a SVN client.
For convenience, it is recommended that you install [http://tortoisesvn.net/downloads TortoiseSVN] on your machine, as this is a lot more comfortable. However, if you get a bad feeling when some program is messing with your Explorer menu, then you can use the [http://subversion.tigris.org/project_packages.html svn command-line client] equally well.

It is generally a good idea to install the command-line client (and adding it to PATH) even if you use TortoiseSVN for convenience. The <tt>autorevision</tt> tool which is used during the build of Code::Blocks makes use of the <tt>svn</tt> binary if it is available. This is preferable to the manual parsing of the entries file that is used as fall-back.

Please do note that working copies checked out with the 1.4 version of Subversion are no longer compatible with earlier versions (Subversion will transparently update existing repositories).

The built-in fall-back mechanism in <tt>autorevision</tt> has been updated to the new 1.4 format and will no longer work with the old format.<br>
Therefore, if you use a Subversion client from the 1.0-1.3 line, you ''must'' put the command line tool into <tt>PATH</tt> for a successful build.<br>
If you use Subversion 1.4, then it is good practice nevertheless, but you can do without, too.

=== svn.exe ===
If you want to show the SVN number in your code::blocks dialog box.

[[Image:Svn number.png|300*300px]]

You should also let svn.exe exist in the PATH of your windows system.
A command line SVN package can be download here [http://www.open.collab.net/downloads/subversion/ CollabNet Subversion Command-Line Client v1.6 (for Windows)].

=== zip.exe ===

You'll also need a working 'zip' program.
If you have the version listed on our [[MinGW installation#Other developer tools|tools page]], you'll be fine.

The zip program coming with cygwin will ''not'' work properly. You do ''not'' need WinZip.

Make sure the zip binary is in your PATH so the <tt>update.bat</tt> script will be able to find it (alternatively, you can edit the batch file, setting the ZIPCMD variable to something else).

The easiest way is to put zip.exe into <tt>bin</tt> inside your MinGW installation directory (that folder is normally in the path).

=== Code::Blocks sources ===

You will also (obviously) need the Code::Blocks sources.

Using ''TortoiseSVN'', make a folder where you want to store the sources, right-click on the folder, and select "SVN Checkout...".

[[Image:Win svn checkout.png]]

In the top box, enter svn://svn.berlios.de/codeblocks/trunk and hit the OK button.

Using ''svn'', you have to open a command prompt ("DOS Window"). Make a folder, change directory, and run svn:

mkdir codeblocks-head
cd codeblocks-head
svn checkout <nowiki>svn://svn.berlios.de/codeblocks/trunk</nowiki>

== Unicode Build ==

=== Compile wxWidgets in Unicode mode ===

After unpacking the zip file to a directory of your choice, open a cmd prompt, and navigate to the folder build/msw inside the wxWidgets folder. Use the following commands to compile wxWidgets:

set path=c:\mingw\bin;c:\mingw\mingw32\bin
mingw32-make -f makefile.gcc USE_XRC=1 SHARED=1 MONOLITHIC=1 BUILD=release UNICODE=1 clean
mingw32-make -f makefile.gcc USE_XRC=1 SHARED=1 MONOLITHIC=1 BUILD=release UNICODE=1

This assumes your MinGW installation is in C:\mingw. Use a different path if you installed MinGW somewhere else.

You will see a lot of warning messages during compilation. Don't worry, this is normal, you are compiling wxWidgets. The build process may take 10-30 minutes, depending on your computer's speed.

If you are using a recent version of MinGW you may find that the object files are too large and that the linker runs out of memory. To fix this problem you need to edit config.gcc so that inline functions are not exported, by modifying the CFLAGS and CXXFLAGS lines to:

CFLAGS ?= -fno-keep-inline-dllexport

CXXFLAGS ?= -fno-keep-inline-dllexport

''remark: If you want to use wxWidgets not only for building Code::Blocks, but also for writing wxWidgets programs, and if you want to use the debugger in those programs, you have to compile a debug build of wxWidgets as well.''
''Use the same commands as for the release build, but replace "release" by "debug".''

'''Optional:'''

To reduce the size of your wxWidgets library, you can disable features which are not used by Code::Blocks. However, you should not do this unless you know what you are doing. You have to delete the generated setup.h from lib/gcc_dll/msw/wx before building, because your changes to include/wx/msw will otherwise not be honoured.

=== Compile Code::Blocks ===
Now, before this step, you have prepared all the stuff to build code::blocks. It's very interesting that we use code::blocks to build code::blocks binaries.

==== Open project====
Open the project file '''CodeBlocks.cbp'''. You will be prompted to define the global variable $(#wx). Enter the location where you unpacked wxWidgets.

[[Image:Global_variable.png]]

[[Image:Global_variable2.png]]

====Compile project====
Hit the blue gear and lean back. Compilation may take 3-5 minutes, depending on the speed of your computer.

[[Image:Win build button.png]]

[[Image:Win build target.png]]

[[Image:Win build finish.png]]

====Copy wxWidgets support DLL====
After the compilation has finished, copy <tt>lib\gcc_dll\wxmsw28u_gcc_custom.dll</tt> from the wxWidgets directory to the <tt>src\devel</tt> directory inside the Code::Blocks source folder (it will also work if you keep a copy of that library in your Windows folder or anywhere in your system path, but this is generally not recommended because you can get into dll hell).

[[Image:Win output folder.png]]

[[Image:Win copy dll.png]]

====Runing script file====
Run <tt>src\update.bat</tt> (located in the root source directory). This will pack the resource files and copy libraries and plugins to their correct locations.

[[Image:Win run bat.png]]

The stripped ("production") executable is found in <tt>output</tt> folder together with all libraries and data files. If you want a version with debug symbols instead (caution: huge size!), use the one found in the <tt>devel</tt> folder.<br>
Congratulations, you own a freshly built version of Code::Blocks!

[[Image:Win final folder.png]]

====Note for future updates====
Go to the Code::Blocks root directory and run <tt>svn update</tt> (or use TurtoiseSVN to the same effect).<br/>
Then open and build the project as described before (and any contrib plugins that you wish to use), and re-run <tt>src\update.bat</tt>.

=== Install Code::Blocks ===

Copy the folder output to where you want Code::Blocks to reside.

=== Compile contributed (or your own) plugins ===

The workspace file '''ContribPlugins.workspace''' contains the project files for all contributed plugins. Open that workspace and compile the plugins which you would like to use (or select "Build Workspace" from the context menu if you want them all).<br/>

[[Image:Contribute plugin.png]]

When you open the contrib plugins workspace, you will be asked to define the <tt>$(#cb)</tt> global compiler variable. This is the path that contains the sdk folder normally this is codeblocks\src. The build process uses this information to place the plugins and data files into the correct place. Enter the location of the Code::Blocks sources in the same way as for the <tt>$(#wx)</tt> variable earlier.

Don't forget to run update.bat again after building the contrib plugins.

== ANSI Build ==

<div style="background-color: #f7d9d9; border: 1px solid #000">
<div style="margin: 5px;">

==== DEPRECATION WARNING: ====
As of February 2006, the official default build for Code::Blocks is '''Unicode''' (see above). Although ANSI builds are technically possible, we discourage their use unless there is a good reason.<br/>
''Support for ANSI builds is likely to be dropped after Version 1.0 is out.''

There is hardly any good argument against using a Unicode build if your OS supports Unicode, even if you do not understand any other language than English, as a Unicode version guarantees that it will be able to work with whatever languages you may possibly encounter in the future -- at a very reasonable cost.

However, if you absolutely don't care about Unicode or if you are bound to use Windows 95, then you may want to build an ANSI version nevertheless.

</div>
</div>

==== Compile wxWidgets in ANSI mode ====

After unpacking the zip file to a directory of your choice, open a cmd prompt, and navigate to the folder build/msw inside the wxWidgets folder. Use the following commands to compile wxWidgets

set path=c:\mingw\bin;c:\mingw\mingw32\bin
mingw32-make -f makefile.gcc USE_XRC=1 SHARED=1 MONOLITHIC=1 BUILD=release UNICODE=0 clean
mingw32-make -f makefile.gcc USE_XRC=1 SHARED=1 MONOLITHIC=1 BUILD=release UNICODE=0

This assumes your MinGW installation is in C:\mingw. Use a different path if you installed MinGW somewhere else.

You will see a lot of warning messages during compilation. Don't worry, this is normal, you are compiling wxWidgets. The build process may take 10-30 minutes, depending on your computer's speed.

'''Optional:'''

To reduce the size of your wxWidgets library, you can disable features which are not used by Code::Blocks. However, you should not do this unless you know what you are doing. You have to delete the generated setup.h from lib/gcc_dll/msw/wx before building, because your changes to include/wx/msw will otherwise not be honoured.

==== Compile Code::Blocks ====

Open the project CodeBlocks.cbp. You will be prompted to define the global variable $(#wx) if you have not used it before. Enter the location where you unpacked wxWidgets.

'''Important:''' The project file is set to compile an Unicode version of Code::Blocks by default. To make an ANSI build, you have to make the following two changes to build options before compiling:
1. In the "Compiler" tab, under "#defines", remove the entry wxUSE_UNICODE.
2. Under "Custom variables", set the variable WX_SUFFIX to empty (default value: u).

Hit the blue gear and lean back. Compilation may take 3-5 minutes, depending on the speed of your computer.

After the compilation has finished, copy wxmsw28u_gcc_custom.dll from lib\gcc_dll inside the wxWidgets directory to the devel directory inside the Code::Blocks source folder (it will also work if you keep a copy of that library in your Windows folder or anywhere in your system path, but this is generally not recommended because you can get into [[wikipedia:DLL Hell|dll hell]]).
Run update.bat (located in the root source directory). This will pack the resource files and copy libraries and plugins to their correct locations.
The location of executable is src\output in C::B tree. From here you'll not need the nightly build anymore.

One little note for svn updates and rebuilds : just go into the codeblocks root directory and do '''svn update''' (or use Turtoise svn).

Then run the src/output/codeblocks.exe, reload project, build it, reload plugins workspace, build it, quit codeblocks and re-run update.bat. You'll have an up-to-date C::B in 3 minutes !

==== Install Code::Blocks ====

Copy the folder output to where you want Code::Blocks to reside.

==== Compile contributed (or your own) plugins ====

The workspace file ContribPlugins.workspace contains the project files for all contributed plugins. Open that workspace and compile the plugins which you would like to use (or select "Build Workspace" from the context menu if you want them all). Don't forget to run update.bat again after building the contrib plugins.

Note that the Nassi Shneiderman plugin (part of the contrib plugins) has a dependency on [http://www.boost.org boost] which is needed to compile this plugin. Boost does not need to be compiled therefore.