Code::Blocks - User contributions [en]

Code Completion Design

2010-08-06T08:07:13Z

Frithjofh:

[[Category:Developer Documentation]]
==How to build==
===Get the source code===
When you download the svn source code of code::blocks,(see here [[Installing_Code::Blocks_from_source_on_Windows#Code::Blocks_sources]] the source code of CodeCompletion plugin was already included.

Here is the screen shot when I opened the codecompletion source code in C::B's source navigator view.

[[Image:Devcc1.png|300x300px| Code completion source tree opened in code::blocks]]

===Build the code completion plug-in===
If you only want to build the Code Completion plug-in, you can select it in the "build target list" (Note: by default, the Build target option was "ALL", which means all the targets in the current workspace will be build), see the screen shot below:

[[Image:Buildcc.PNG|frame|none| Code completion build target option in code::blocks]]

Don't forget to run the batch script file "update.bat" after you build the target, this procedure will update your output folder package and strip the debug information. See the wiki page [[Installing_Code::Blocks_from_source_on_Windows]] for more information.

===A brief description of every project files===
From now on, we use '''CC''' as an abbreviation for '''code completion plug-in'''.
{|border="1" cellpadding="1" cellspacing="0" style="font-size: 100%; border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100% table-layout: unfixed;"
|-
| ccdebuginfo.cpp || a dialog for debugging CC, can be opened by double click on the code browser tree entry with shift and ctrl key pressed
|-
| ccoptionsdlg.cpp|| code completion options dialog, can be opened by menu->setting->editor->code completion and symbols browser
|-
| ccoptionsprjdlg.cpp|| setting the additional parser search path
|-
| classbrowser.cpp||viewing the symbols tree ctrl(token tree).
|-
| classbrowserbuilderthread.cpp|| a thread to build the class browser tree above
|-
| codecompletion.cpp ||The Main file need by code completion plug-in, maintain all the CC's GUI and native parser
|-
| insertclassmethoddlg.cpp|| a dialog to insert class method, can be open by context menu in editor
|-
| nativeparser.cpp||a class derived from wxEvtHandler, NativeParser class has a member variable "Parser m_Parser";
|-
| selectincludefile.cpp|| select multiply matched token names before any jump to declaration or jump to implementation.
|-
|parser/parser.cpp|| Parser class was also derived from wxEvtHandler, can start batch parse... this class has member variables like :cbThreadPool m_Pool(which will create a thread from thread pool for each file need passed);TokensTree* m_pTokens(contains all the Token database);
|-
|parser/parserthread.cpp||will do the syntax analysis for every file in a project, it has a Tokenizer as member variable
|-
|parser/token.cpp|| definition of the "Token" class, and TokensTree(which means the Token dababase)
|-
|parser/tokenizer.cpp|| tokenizer will return every wxString it regard as a symbol by GetToken(), also do a replacement before return
|-
|parser/searchtree.cpp|| implement the patricia search tree using by TokensTree
|-
|Header files|| no description needed
|}

==Low level parser(Lexical analysis, Tokenize)==
For someone haven't heard what does "Token" and "Tokenize" mean, you should read the wikibooks article [http://en.wikibooks.org/wiki/C%2B%2B_Programming/Compiler#Compilation A brief explain of what does a parser do] and [http://en.wikipedia.org/wiki/Lexical_analysis Tokenize on wikipedia]. Shortly, a Tokenizer regards your C++ or C source code as a large array of characters (sometimes, we call it a string), then this big string can be divided to small atomic strings----a '''token''' (Each token has a unique meanings and can't be divided into sub-strings. A token can be a symbol, an identifier, a keyword, a digital number, etc), meanwhile "white spaces" and "comments" were ignored by the Tokenizer.

for a simple c++ program like below
<source lang = "c">
int main()
{
std::cout << "hello world" << std::endl;
return 0;
}
</source>
After tokenizing, it should give these 15 tokens
<source lang = "cpp">
1 = string "int"
2 = string "main"
3 = opening parenthesis
4 = closing parenthesis
5 = opening brace
6 = string "std"
7 = namespace operator
8 = string "cout"
9 = << operator
10 = string ""hello world""
11 = string "endl"
12 = semicolon
13 = string "return"
14 = number 0
15 = closing brace
</source>

===Tokenizer class===
A class named '''Tokenizer''' was implemented in "tokenizer.h" and "tokenizer.cpp". Seen from the Tokenizer's level, a token is just a [http://docs.wxwidgets.org/stable/wx_unicode.html unicode] wxString. There are several steps to run an instance of Tokenizer.
===preparing the big string===
From the previous section, you know the Tokenizer is just a string cutter. So, the first step is preparing the big string. The string can either be loaded from a source file or a memory buffer. Currently, the Unicode wxString is used.(since we are all using Unicode build of code::blocks, and ANSI mode is outdated and deprecated).
===Get or Peek a token===
'''Tokenizer''' contains a '''file position indicator'''----m_TokenIndex(see [http://en.wikipedia.org/wiki/Fopen File Open In C language]) pointing to the current position of string. So, you can '''Get''' a token or '''Peek''' a token. Here is the function prototype
<source lang = "cpp">
//Get the current token string started from m_TokenIndex,
//After that, increase the m_Tokenindex
wxString GetToken();

//Peak the current token string and but do *NOT* increase the m_TokenIndex
wxString PeekToken();
</source>

For example, if the Tokenizer parses the example code above, you can see how these two methods work.

*After initializing the Tokenizer(preparing the big string), You firstly call the GetToken() function, which will return the first token "int" and increase the m_TokenIndex one step to "int".

*Then, if you call the PeekToken(), which will return a token "main", but the tokenindex was still remaining point to "int".

*If you call the GetToken() again, it will return a "main" immediately and increase the file pointer to "main".

Note: Internally, the Tokenizer class use a '''undo and peek cache''' to do the trick. Once a token is peeked, it is saved in '''m_Peek''' member, so, next time you call GetToken(), it just immediately return the cached value without calling the "DoGetToken()" procedure again.

[[Image:Cb token cache.png]]

===Nested Value of braces===
As you know, braces are exist in pairs, such as "{" and "}", or "[" and "]", Also, these braces can be embeded. So the Tokenizer keep a value '''m_NestLevel''' to indicate how deep you stays. If the Tokenizer meets a '''{''', it will increase the nestValue, and if it meets a '''}''', it will decrease the m_NestLevel. See the pseudo code in Tokenizer.cpp below:
<source lang = "cpp">
if (CurrentChar() == '{')
++m_NestLevel;
else if (CurrentChar() == '}')
--m_NestLevel;
</source>

===SkipUnwanted tokens===
A '''bool''' member variable '''m_SkipUnwantedTokens''' determines whether a regular assignments statement will be omitted or not. For example, a piece of code below:
<source lang = "cpp">
a = b + c;
</source>

If m_SkipUnwantedTokens == true, then once SkipUnwanted() meets the "=" symbol, it will go on skipping every characters until it meets ''',''' or ''';''' or '''}''', so this statement will be omitted by the Tokenizer.

Sometimes, this behavior becomes a nightmare when parsing the statement like default argument in template. Or the default arguments in function.
<source lang = "cpp">
// assignment statement in template arguments
template<class T = int>
class abc {
T m_a;
......
......
}

// assignment statement in function arguments

void foo( int arg1 = 60 )
{
bla bla;
}
</source>
If the Tokenizer finds that an equation sign '''=''', it will skip any character until it meets a '''}''', so, the class declaration or function body will be totally skipped in the unexpected way. In this case, we should manually '''disable''' this functionality by setting m_SkipUnwantedTokens = false to let the Tokenizer parse these statements correctly.

That's why you will see many situations when you enter a function, you should save the m_SkipUnwantedTokens statues and disabled it, when you leave a function, you should manually restore it.(See function implementation in ParseThread.cpp)

===Return a correct token, Macro replacement===
Special token should be replaced for parsing correctly. For example, in the standard c++ header (mingw), there are a string named "_GLIBCXX_STD", this should be replaced to "std". See the dialog below.

[[Image:Cc std replacement.png|400x400px|]]

The inline function in the Tokenizer class will check whether a token should be replaced before return.

<source lang = "cpp">
wxString Tokenizer::MacroReplace(const wxString str)
{
wxStringHashMap::const_iterator it = s_Replacements.find(str);

if (it != s_Replacements.end())
{
// match one!
wxString key = it->first;
wxString value = it->second;
TRACE(_T("MacroReplace() : Replacing '%s' with '%s' (file='%s')."), key.wx_str(), value.wx_str(), m_Filename.wx_str());
if (value[0]=='+' && CurrentChar()=='(')
{
unsigned int start = m_TokenIndex;
m_Buffer[start] = ' ';
bool fillSpace = false;
while (m_Buffer[start]!=')')
{
if (m_Buffer[start]==',')
fillSpace = true;

if (fillSpace==true)
m_Buffer[start]=' ';

start++;
}
m_Buffer[start] = '{';
return value.Remove(0,1);
}
else if (value[0] == '-')
{
unsigned int lenKey = key.Len();
value = value.Remove(0,1);
unsigned int lenValue = value.Len();

for (unsigned int i=1; i<=lenKey; i++)
{
if (i < lenValue)
m_Buffer[m_TokenIndex-i] = value[lenValue-i];
else
m_Buffer[m_TokenIndex-i] = ' ';
}

int firstSpace = value.First(' ');
// adjust m_TokenIndex
m_TokenIndex = m_TokenIndex - lenValue + firstSpace;

return value.Mid(0,firstSpace);
}
else
return value;
}

return str;
}

</source>

[[Image:Cc replace dialog.png|400x400px|none| Code completion build target option in code::blocks]]

Setting the replacement mapping. Note that before return a token, a replacement map was searched to check if it matches any entry in the map, so, the bigger this map goes, the slower it will do parsing.

Note: Code Completion plug-in is not a preprocessor, so it is difficult to deal with the source mixed with many macro, or some strange macros. This is something like Ctags' replacement options "?I identifier?list" in [http://ctags.sourceforge.net/ctags.html#OPERATIONAL%20DETAILS ctags option detial] or [http://codelite.org/LiteEditor/FAQ Code Completion macro FAQ]

For discussion of Ctags, the related thread is [/index.php/topic,10564.msg72424.html#msg72424 Re: namespaces and code completion] and [/index.php/topic,11187.msg77135.html#msg77135 Re: New code completion remarks/issues]

===replacement rules===
====directly replacement AAAAA -> BBBBB====
You can define a rule:
AAAAA -> BBBBB

Which means, if the tokenizer meet a string "AAAAA", then it will returned a string "BBBBB"
==== AAAAA -> +BBBBB====
For example, when

<source lang = "cpp">
_GLIBCXX_BEGIN_NESTED_NAMESPACE(std, _GLIBCXX_STD_D)

/// See bits/stl_deque.h's _Deque_base for an explanation.
template<typename _Tp, typename _Alloc>
struct _Vector_base
{
typedef typename _Alloc::template rebind<_Tp>::other _Tp_alloc_type;

......

_GLIBCXX_END_NESTED_NAMESPACE
</source>

We should replace the string "_GLIBCXX_BEGIN_NESTED_NAMESPACE(std, _GLIBCXX_STD_D)"
to "namespace std {", here, we introduce two replacement rules:
{|border="1" cellpadding="1" cellspacing="0" style="font-size: 100%; border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100% table-layout: unfixed;"
|-
| _GLIBCXX_BEGIN_NESTED_NAMESPACE || +namespace
|-
| _GLIBCXX_END_NESTED_NAMESPACE || }
|}

In this rule, we firstly replace the "_GLIBCXX_BEGIN_NESTED_NAMESPACE" with the "namespace", then, we reserve the "std", and change the closing parenthesis to an opening brace. (See the image above), also, every token string "_GLIBCXX_END_NESTED_NAMESPACE" will be replaced by "}".
[[File:CCreplacement_rule.png]]

So, the code becomes to like below:
<source lang = "cpp">
namespace std {

/// See bits/stl_deque.h's _Deque_base for an explanation.
template<typename _Tp, typename _Alloc>
struct _Vector_base
{
typedef typename _Alloc::template rebind<_Tp>::other _Tp_alloc_type;

......

}
</source>
==== AAAAA -> -BBBBB====

For example, when
<source lang = "cpp">
_GLIBCXX_BEGIN_NAMESPACE_TR1
...
...
_GLIBCXX_END_NAMESPACE_TR1
</source>

We should replace the string "_GLIBCXX_BEGIN_NAMESPACE_TR1"
to "namespace tr1 {", here, we introduce two replacement rules:
{|border="1" cellpadding="1" cellspacing="0" style="font-size: 100%; border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100% table-layout: unfixed;"
|-
| _GLIBCXX_BEGIN_NAMESPACE_TR1 || -namespace tr1 {
|-
| _GLIBCXX_END_NAMESPACE_TR1 || }
|}

In this rule, we firstly replace the "_GLIBCXX_BEGIN_NAMESPACE_TR1" with the "namespace", then, add aditional string "tr1 {"

So, the code becomes:
<source lang = "cpp">
namespace tr1 {
...
...
}
</source>

==== AAAAA -> *====
In this case, we call it a "strip the next "(" and ")" rule. for example:

The rule syntax is:

XXXXXX -> *

For example, In the source code below:
<source lang = "cpp">
CVAPI(void) cvFxxxx();
CVAPI(cvMat *) cvFyyy();
</source>

will become to (if I add a replacement rule CVAPI -> *)

<source lang = "cpp">
void cvFxxxx();
cvMat * cvFyyy();
</source>

==High level parser(Syntax Analysis)==
This is the main flow of a parser.

[[Image:Parser_Flow.gif]]
===parser thread===
Basically, we can say, the low level parser(Tokenizer) moves its pointer character by character, and return a wxString(token) to feed the high level parser(Syntax analyzer).All the syntax analysis was done in ParserThread. A thread must be created to parse a source file. see parserthread.cpp and parserthread.h, a thread will be allocated from thread pool. For example, a file contains these statement:
<source lang = "cpp">
void f1();
int f2(char c);
float f3(void * p);
int f1;
double f2;
</source>
After the ParserThread finished its parsing, it will recognize five tokens, which has the keyword "f1","f2" and "f3", note, tokens can have the same names, but they differ from different types( variables, functions...).

===Token class===
How can a large number of tokens be recorded? A '''Token'''(note: it as a capital means it's class type) class was introduced to recorded every token. For boosting the speed of allocating Tokens, the "new" and "delete" operator were overloaded in its base class BlockAllocated. See the [http://en.wikipedia.org/wiki/Memory_pool memory pool] page on wikipedia as a reference.
<source lang = "cpp">
class Token : public BlockAllocated<Token, 10000>
{
......
wxString m_Type; // this is the return value (if any): e.g. const wxString&
wxString m_ActualType; // this is what the parser believes is the actual return value: e.g. wxString
wxString m_Name;
wxString m_Args;
wxString m_AncestorsString; // all ancestors comma-separated list
unsigned int m_File;
unsigned int m_Line;
unsigned int m_ImplFile;
unsigned int m_ImplLine; // where the token was met
unsigned int m_ImplLineStart; // if token is impl, opening brace line
unsigned int m_ImplLineEnd; // if token is impl, closing brace line
TokenScope m_Scope;
TokenKind m_TokenKind;
bool m_IsOperator;
bool m_IsLocal; // found in a local file?
bool m_IsTemp; // if true, the tree deletes it in FreeTemporaries()
bool m_IsConst; // the member method is const (yes/no)

int m_ParentIndex;
TokenIdxSet m_Children;
TokenIdxSet m_Ancestors;
TokenIdxSet m_DirectAncestors;
TokenIdxSet m_Descendants;
......

};
</source>
You can see the Token class contains all the information needed for recording its locating, its type or class derived hierarchy...

For example, in the source code in[Low level parser(Lexical analysis)]. A Token for "main" should contains it's name (obviously , m_Name="main" ), then m_File will record which file dose this Token exist. m_Line will give the line number of "main" in this source file, and so on.

===Memory Pool--BlockAllocated class===
In BlockAllocated class, there is only a static member say "static BlockAllocator<T, pool_size, debug> allocator;" to keep all the pre-allocated memory for all derived class.

'''10000''' means a pool of 10000 Tokens were allocated in the memory pool, so, dynamically allocate a Token object will be fast and efficient.

[[Image:Cb blockalloc.png|frame|none| Operator new overloading for fast allocate in the heap]]

===ParserThread===
The function Parse() will do the most job of syntax analysis. See the pseudo code below.
<source lang = "cpp">
ParserThread::Parse()
{
......
do
{
......
DoParse();
......

}while(false);

return result;
}

</source>

In the DoParse(), it checks the token from Tokenizer. For example, if the token words = "enum", then, the ParserThread::HandleEnum() will do the job to parse this enum block.

===A simple look ahead parser===
We can explain a little about it parser, the member variable '''m_Str''' of class ParserThread will be considered as a '''type stack''', for example, we want to parse the statement below:

<source lang = "cpp">
symbolA symbolB symbolC symbolD;
</source>

Only symbolD can be recognized as a variable, and it has a type of "symbolA symbolB symbolC". When the parser meets each symbol, it will look ahead to see the next token is whether ";", if not, the current token will '''pushed''' to m_Str. These iteration will be ended when the parser look ahead one step from symbolD and find the next token is a ";".

===DoParse Examples===
====Handling class declaration====
The main routing of handling class was in
ParserThread::HandleClass function
If the parserThread meet these statement
<source lang = "cpp">
class AAA{
int m_a;
int m_b;
} ;
</source>
It will surely add a Token of "AAA", it's type is "class".

What about these statements
<source lang = "cpp">
class AAA{
int m_a;
int m_b;
} x,y,z;
</source>
The parserThread should firstly add a Token "AAA", then it should regard "x", "y", "z" are three variables of type "AAA". This was done by "ReadVarNames()" function, it will read every comma separated variables after a class declaration.

====Handling typedef statement====
Sometimes, you can see these code blocks:
<source lang = "cpp">
typedef class AAA{
int m_a;
int m_b;
} BBB,CCC;
</source>
If the parser meets the keyword "typedef", firstly it set the "m_ParsingTypedef = ture" to indicate that we are parsing a typedef statement.

Next, it meets a keyword "class", which also indicate it is a class declaration. So, the HandleClass function will do the task. A Token of "class AAA" will be added to the TokensTree. Wait a minute, how can we deal with "BBB" and "CCC", this is not the same case as previous code, we can't regard "BBB","CCC" as variables. In this case, another function "ReadClsName()" will be called. For simplicity of TokensTree, we just regard "BBB" and "CCC" as derived class of "AAA".

How does the parserThread know between these two cases. Here is the code:

<source lang = "cpp">
if (m_ParsingTypedef)
{
m_Str.Clear();
ReadClsNames(newToken->m_Name);
// m_ParsingTypedef = false;
break;

}
else
{
m_Str = newToken->m_Name;
ReadVarNames();
m_Str.Clear();
break;
}
</source>

That's the whole thing I would like to write about handling class and handling typedef.

==TokensTree&SearchTree==
Maybe, you would ask a question: where do these Tokens store? The answer is that all the Tokens will be recorded in "TokensTree class".

When a certain Token is identified(whether it's a global variable, a class declaration, a class member function, and so on), it will be inserted to a database(TokensTree).

Furthermore, for fast Token query, Tokens should be sorted by it's wxString m_Name member;

A '''compact Patricia tree'''(see the wikipedia [http://en.wikipedia.org/wiki/Radix_tree Patricia tree on wikipedia]) is built to hold all their names.

For example, If you add three item to the TokensTree.
<source lang = "cpp">
mytree->AddItem(_T("physics"),_T("1 - uno"));
mytree->AddItem(_T("physiology"),_T("2 - dos"));
mytree->AddItem(_T("psychic"),_T("3 - tres"));
</source>

The Patricia tree structure will show as below, the edge of a tree contains a "label string" and the number in parentheses refers to a node Id.

<source lang = "cpp">
- "" (0)
\- "p" (4)
+- "hysi" (2)
| +- "cs" (1)
| \- "ology" (3)
\- "sychic" (5)
</source>
===Animation of Patricia tree===
A web page gives an animation of building a Patricia tree, you can see how the tree node added. See here [http://bootstrapping.wordpress.com/2008/01/24/prefix-searching-with-radix-tree/ Prefix searching with Radix Tree]

===SearchTree Node===
A Node should contains at least several essential element. They are:
# An edge: in the image below, the gray filled area shows a Node, since each edge belong to the next node, for example, the Node has an edge "abcd".
# SearchTreeItemMap: because our searchTree is a compact Patricia tree which means an edge contains many items. Such as, "ab" , "abc", "abcd" all the suffix string belong to the edge "abcd"
# SearchTreeLinkMap: This is an associated container map<wxChar,NodeId>, which store all "pointers" to its child Node. In the example below, "e" points to a Node of "efg", while "x" points to "xyz".
# Node depth: depth of Search Tree Node is defined by the string length from the "root node". See a depth of each node on the search tree above. For example, the Node of "hysi" has a m_Depth = 5 ("" + "p" + "hysi" = 5).

===Node Lable===
For example, the node "hysi" (2) has two children, they are "cs" (1) and "ology" (3), show below.

[[Image:Cb tree node lable.png]]

For more information, see the forum discussion here. [/index.php/topic,1696.0.html rickg22's SearchTree development] as a reference.

===How to query a Token by a keyword===
The parser collect all the Token information, and stored them in the TokensTree, the GUI function can query keywords from the database to show function tips or to build a Class Browser tree.

For example, if you want to find all the Tokens named "ab". In the picture above from TokenDatabase(TokensTree). we can search on the Patricia tree containing all the Tokens names, finaly, we find a tree node with a edge "abcd". So, "ab" is in it's Node's items list. Then, we can find a TokenIdxSet in a vector<TokenIdxSet>, this TokenIdxSet has all the index named by "ab", so, we can get the result like: There are many Tokens named "ab".Token "ab" may be a member varialbe name in a class, or a global function name...

<source lang = "cpp">
ClassA::ab
ClassB::ab
void ab()
....
</source>

[[Image:CCTokenTree1.png]]

==Flexible Parser structure==
The Parser class( in Parser.cpp and Parser.h ) has re-factored to support every project associate with a Parser object (svn revision > 6268 ). Which means: One Parser object per project, so, every project (xxx.cbp) will hold its own Token macro defines and Token trees.

Due to the new introduced conditional preprocessor handling mechanism, the same source file may give different Tokens due to the different macro defines in different project. Also, CC support parsing on the files which does not belong to any project.

#You open a project in CB, then all the files belong to the project( related to the project) will be parsed in CC.
#Now, you open another file( we call it a "separate file" later) which is not belong to the current project nor any other opened project.
#Then the CC will create a "temporary parser" named "NONE“ parser, and add this separate file to the "NONE" parser.
#So, you can still see the class tree when viewing the separate file.
#Once you close this separate file, the "NONE" parser will automatically be removed.

The main idea is: Now, We can let the CC do parse on some separate files
and support class browsing in Symbol browser.

==Automatic Code Completion==
===Find the search scope===

[[Image:CC SearchScope.png]]

For example, when you are editing, and the caret position was located at "E" as shown in the above image, the first thing doing an automatic code completion is find the '''search scope'''.

Here are some steps to get the initial(first) search scope:

*First, you need to correct all the "using namespace XXXX" directives at the beginning the the current source file.(labeled with "A"), this means all the child tokens of "namespace Scintilla" should be searched.
*Secondly, find the function body where the current caret position locates. eg, the above code, the caret is in the "RunStyles::RunFromPosition()" function, so the function parameter variable "position"(labeled with "C" and the local variable "run" (labeled as "D") is also a matching Tokens.
*Thirdly, look at the "B", this means we are in the class named "RunStyles", so, "RunStyles" is also a search scope.
*Finally, don't forget the global namespace scope, because the tokens of this scope are exposed to everywhere of the source.

===Break up the current statement===
<source lang = "cpp">
VariableA.m_VariableB.Functi
</source>
If you are entering the above statement, the caret is behind the "Functi". Then the whole line will be break up to several "parsing component".

There are three components: "'''VariableA'''" , "'''m_VariableB'''" and "'''Functi'''". In the next section, I will introduce that the AI matching routing will start from matching the first component with the initial(first) search scope.

===Do an AI match===
Doing an AI match is just like a walking on a tree, and find the final matching result.See the image below:

[[image:CC AI Match.png]]

'''Here is the matching algorithm''':

Now, suppose we have an initial "search scope", and a "component" array.

The AI match algorithm starts from matching the "sub search scopes" with the first "component", then, the matched "sub search scope"(red rectangle) will be the initial "search scope" again matching with the second "component", this matching routing is running continuously until we matches with the final component. Then we get the whole matching result, that will be show as a auto code completion list.

==Code completion debugging support==
===Debug Log output===
If you want to debug your plug-in, you may need to Logout the debug message to the "Code::Blocks Debug" panel. Here is the sample code:

<source lang = "cpp">
Manager::Get()->GetLogManager()->DebugLog(_("XXXXX "));

wxString name;
wxString args;
wxString m_Str;
//.....
Manager::Get()->GetLogManager()->DebugLog(F(_T("Add token name='")+name+_T("', args='")+args+_T("', return type='") + m_Str+ _T("'")));

</source>

Also, you need start the Code::Blocks with the command line argument. For example in windows.

'''codeblocks.exe --debug-log'''

then a Code::blocks debug panel will be shown to display the log.
[[Image:CbDebugLog.png|frame|none| Debug Log output panel]]

===Code-Completion debug tool dialog===
When you press '''shift''' and '''ctrl''' key and double click on any entry of the navigator tree entry, a debug tool dialog will pop up to give a more detail about the selected token. You can query its information such as its member variables, its Ancestors and so on.

[[Image:CcDebugToolDialog.png]]

===Debug Smart Sense log output ===
When you hold the'''shift''' and '''ctrl''' key and right click on any entry of the navigator tree entry, the context menu will have a "Debug SmartSense" menu entry shown. You can click it to enable it. See the image blow. Then, all the debug log information when doing an Auto-completion will be shown in the "Debug Log" panel.

[[File:Cc debug smartsense.png]]

==Usefull Links==

*A discussion on search tree in the forum [/index.php/topic,1696.0.html] and [/index.php/topic,1581.0.html].

*Another opensource IDE [http://vcfbuilder.org/?q=node/139 VCF builder]or[https://sourceforge.net/projects/vcfbuilder/ vcfbuilder on sf], By the way , VCF use a CodeStore based on [http://www.antlr.org/ antlr parser] to deal with parsing, the whole source code can be check out from
<source lang = "cpp">
svn co https://vcfbuilder.svn.sourceforge.net/svnroot/vcfbuilder vcfbuilder
</source>

*online book[http://www.macs.hw.ac.uk/~alison/alg/details.html Data Structures and Algorithms II Course ] and [http://www.macs.hw.ac.uk/~alison/alg/lectures.html pdf lectures]

*A forum discussion on why a standard perprocessor and parser works slowly. [/index.php/topic,2494.msg19801.html#msg19801 parsing iostream header takes 5 seconds]

*[http://www.codelite.org CodeLite] is another open source IDE using wxWidgets, use Ctags as a indexing service, and do context expression syntactic analysis generated from Lex and Yacc tools.See the explanation in forum message by it's author eranif [/index.php/topic,10087.msg70875.html#msg70875 How does Codelite's CC work with CTags and Yacc&Lex]

*Hopefully, we can use the patricia tree from the standard library, see here:[http://gcc.gnu.org/onlinedocs/libstdc++/ext/pb_ds/trie_based_containers.html trie]

* a blog from KDE4's developer, it explain the code completion in KDE4, see here:[http://zwabel.wordpress.com/ zwabel' blog]

* QT creator source code from [http://qt.gitorious.org/qt-creator/qt-creator/trees/master QT-creator source]

* [http://websvn.kde.org/trunk/KDE/kdevelop/ Kdevelop source code] and it's [http://websvn.kde.org/trunk/KDE/kdevelop/languages/cpp/parser/ parser]

* [http://stackoverflow.com/questions/1220099/how-does-code-completion-work How does code completion work? - Stack Overflow]

* [/index.php/topic,11724.0.html Just a reminder Codelite IDE now have improved it's parser]

*[http://padator.org/software-yacfe.php Yacfe, a parser with proprocessor enabled]

*[/index.php/topic,1581.msg11701.html#msg11701 A Mini C++ interpreter] from the book "The Art of C++ by Herbert Schildt", source code can be download [http://books.mcgraw-hill.com/downloads/products/0072255129/0072255129_code.zip here]

*[http://www.macs.hw.ac.uk/~alison/alg/lectures/l7.pdf Lecture 7: Parsing (intro) (pdf)] and [http://www.macs.hw.ac.uk/~alison/alg/lectures/l8.pdf Lecture 8: Recursive Descent Parsing (pdf)] from [http://www.macs.hw.ac.uk/~alison/alg/lectures.html Data Structures and Algorithms II]

*There are some online "Compiler design" books listed in [http://www.freetechbooks.com/compiler-design-and-construction-f14.html Free Online Compiler Design and Construction Books :: FreeTechBooks.com], and the best one I think is : [http://www.diku.dk/hjemmesider/ansatte/torbenm/Basics/index.html Basics of Compiler Design], and you can get a basic understanding.

Installing Code::Blocks from source on Windows

2009-03-05T18:44:52Z

Frithjofh:

[[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]].

Since November 2007 MinGW-GCC 4.2.1

=== wxWidgets ===

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

Code::Blocks uses
* 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.

=== zip.exe ===

You'll also need a working 'zip' program.
If you have the version listed on our [https://wiki.codeblocks.org/index.php?title=Mingw#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 svn://svn.berlios.de/codeblocks/trunk

== Building ==

=== 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.

''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> 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 into 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 [http://en.wikipedia.org/wiki/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.

Installing the latest official version of Code::Blocks on Windows

2009-03-05T18:40:49Z

Frithjofh:

[[Category:Installing Code::Blocks]]
[[Category:Installing the latest official version of Code::Blocks]]

=== Install steps ===

# [https://www.codeblocks.org/downloads/5 Download the Code::Blocks 8.02 installer]. If you know you don't have MinGW installed, download the package which has MinGW bundled.
# Run the installer, it's a standard installer for Windows; just press Next after reading each screen.
# If you're planning installing a compiler after you've installed Code::Blocks, read the information provided in the installer.
# If you downloaded the installer which doesn't come with MinGW, you may have to configure the compiler manually (usually Code::Blocks' auto detects the compiler).

Installing Code::Blocks

2009-03-04T22:59:04Z

Frithjofh:

[[Category:Installing Code::Blocks]]

[[Compiled packages of Code::Blocks]]

== MS Windows ==

* [[Installing the latest official version of Code::Blocks on Windows]]
* [[Installing Code::Blocks nightly build on Windows]]
* [[Installing Code::Blocks from source on Windows]]

== Linux ==

* [[Installing Code::Blocks from source on Linux]] (applies to all distros)
* [[Installing Code::Blocks before SVN 3893 from source on Linux]] (applies to all distros)

=== Ubuntu ===

:* [[Installing Code::Blocks nightly build on Ubuntu]]

=== Debian ===

:* [http://jens.lody.name/debian/ Installing Code::Blocks nightly build on Debian]

=== Fedora ===

:* [[Installing Code::Blocks nightly build on Fedora]]

=== Blag ===

:* [[Installing Code::Blocks nightly build on Blag]]

=== Gentoo ===

:* [[Installing Code::Blocks from source on Gentoo]]

=== RPM based distributions ===

Such as: Red Hat Linux, Yellow Dog Linux, Fedora Core, CentOS, etc. etc.

:* [[Installing Code::Blocks nightly build on RPM based distributions]]
:* [[Installing Code::Blocks from source on RPM based distributions]]

== BSD ==

=== FreeBSD ===

:* [[Installing Code::Blocks from source on FreeBSD]]

== Solaris ==

* [[Installing Code::Blocks from source on Solaris]]

== Mac OS X ==

* [[Installing Code::Blocks nightly build on Mac OS X]]

* [[Installing Code::Blocks from source on Mac OS X]]

==Working on Code::Blocks sources from within Code::Blocks!==

The following applies for all platforms where you have Code::Blocks installed and working.

After correct install of Code::Blocks you will find two folders under .../trunc/scr , a directory named "devel" and another one named "output".
These two folders will contain the same files and directory structure and you can use the IDE from either of these two directories. This structure has been created so that you can work in Code::Blocks while editing Code::Blocks' sources ;).
Basically, you 'll be using the "output/CodeBlocks.exe" executable. Code::Blocks' project settings are such that all output goes under "devel". So you can edit Code::Blocks' sources inside Code::Blocks and, when pressing "Run", it will run the "devel/CodeBlocks.exe" executable ;). This way, you can't ruin the main executable you 're using (under "output"). When your changes satisfy you and all works well, quit Code::Blocks, run "make update" from command line and re-launch "output/CodeBlocks.exe". You 'll be working on your brand new IDE!

Installing Code::Blocks

2009-03-04T22:58:23Z

Frithjofh:

[[Category:Installing Code::Blocks]]

[[Compiled packages of Code::Blocks]]

== MS Windows ==

* [[Installing the latest official version of Code::Blocks on Windows]]
* [[Installing Code::Blocks nightly build on Windows]]
* [[Installing Code::Blocks from source on Windows]]

== Linux ==

* [[Installing Code::Blocks from source on Linux]] (applies to all distros)
* [[Installing Code::Blocks before SVN 3893 from source on Linux]] (applies to all distros)

=== Ubuntu ===

:* [[Installing Code::Blocks nightly build on Ubuntu]]

=== Debian ===

:* [http://jens.lody.name/debian/ Installing Code::Blocks nightly build on Debian]

=== Fedora ===

:* [[Installing Code::Blocks nightly build on Fedora]]

=== Blag ===

:* [[Installing Code::Blocks nightly build on Blag]]

=== Gentoo ===

:* [[Installing Code::Blocks from source on Gentoo]]

=== RPM based distributions ===

Such as: Red Hat Linux, Yellow Dog Linux, Fedora Core, CentOS, etc. etc.

:* [[Installing Code::Blocks nightly build on RPM based distributions]]
:* [[Installing Code::Blocks from source on RPM based distributions]]

== BSD ==

=== FreeBSD ===

:* [[Installing Code::Blocks from source on FreeBSD]]

== Solaris ==

* [[Installing Code::Blocks from source on Solaris]]

== Mac OS X ==

* [[Installing Code::Blocks nightly build on Mac OS X]]

* [[Installing Code::Blocks from source on Mac OS X]]

==Working on Code::Blocks sources from within Code::Blocks!==

---------------------------------------------------------
The following apply for all platforms where you have Code::Blocks installed and working.

After correct install of Code::Blocks you will find two folders under .../trunc/scr , a directory named "devel" and another one named "output".
These two folders will contain the same files and directory structure and you can use the IDE from either of these two directories. This structure has been created so that you can work in Code::Blocks while editing Code::Blocks' sources ;).
Basically, you 'll be using the "output/CodeBlocks.exe" executable. Code::Blocks' project settings are such that all output goes under "devel". So you can edit Code::Blocks' sources inside Code::Blocks and, when pressing "Run", it will run the "devel/CodeBlocks.exe" executable ;). This way, you can't ruin the main executable you 're using (under "output"). When your changes satisfy you and all works well, quit Code::Blocks, run "make update" from command line and re-launch "output/CodeBlocks.exe". You 'll be working on your brand new IDE!

Installing Code::Blocks

2009-03-04T22:57:45Z

Frithjofh:

[[Category:Installing Code::Blocks]]

[[Compiled packages of Code::Blocks]]

== MS Windows ==

* [[Installing the latest official version of Code::Blocks on Windows]]
* [[Installing Code::Blocks nightly build on Windows]]
* [[Installing Code::Blocks from source on Windows]]

== Linux ==

* [[Installing Code::Blocks from source on Linux]] (applies to all distros)
* [[Installing Code::Blocks before SVN 3893 from source on Linux]] (applies to all distros)

=== Ubuntu ===

:* [[Installing Code::Blocks nightly build on Ubuntu]]

=== Debian ===

:* [http://jens.lody.name/debian/ Installing Code::Blocks nightly build on Debian]

=== Fedora ===

:* [[Installing Code::Blocks nightly build on Fedora]]

=== Blag ===

:* [[Installing Code::Blocks nightly build on Blag]]

=== Gentoo ===

:* [[Installing Code::Blocks from source on Gentoo]]

=== RPM based distributions ===

Such as: Red Hat Linux, Yellow Dog Linux, Fedora Core, CentOS, etc. etc.

:* [[Installing Code::Blocks nightly build on RPM based distributions]]
:* [[Installing Code::Blocks from source on RPM based distributions]]

== BSD ==

=== FreeBSD ===

:* [[Installing Code::Blocks from source on FreeBSD]]

== Solaris ==

* [[Installing Code::Blocks from source on Solaris]]

== Mac OS X ==

* [[Installing Code::Blocks nightly build on Mac OS X]]

* [[Installing Code::Blocks from source on Mac OS X]]

===Working on Code::Blocks sources from within Code::Blocks!===

---------------------------------------------------------
The following apply for all platforms where you have Code::Blocks installed and working.

After correct install of Code::Blocks you will find two folders under .../trunc/scr , a directory named "devel" and another one named "output".
These two folders will contain the same files and directory structure and you can use the IDE from either of these two directories. This structure has been created so that you can work in Code::Blocks while editing Code::Blocks' sources ;).
Basically, you 'll be using the "output/CodeBlocks.exe" executable. Code::Blocks' project settings are such that all output goes under "devel". So you can edit Code::Blocks' sources inside Code::Blocks and, when pressing "Run", it will run the "devel/CodeBlocks.exe" executable ;). This way, you can't ruin the main executable you 're using (under "output"). When your changes satisfy you and all works well, quit Code::Blocks, run "make update" from command line and re-launch "output/CodeBlocks.exe". You 'll be working on your brand new IDE!

Installing Code::Blocks from source on Linux

2009-03-04T22:54:58Z

Frithjofh:

[[Category:Installing Code::Blocks]]
[[Category:Installing Code::Blocks from source]]
These are instructions on how to build Code::Blocks under Linux. These instructions should work for all Linux distros, as we'll be installing from sources.

===Prerequisites===

In order to successfully compile Code::Blocks, the wxWidgets (<u>wxGTK-2.8.0 or later</u>) cross-platform UI library <u>must be installed</u>. In this document, it is not assumed that it is already installed in your system and instructions are given on how to download, build and install it.
What is '''not''' covered here, is the wxWidgets prerequisites. The most important being GTK2, of course!
Let me stress it here, while it's early: <u>GTK2 is required</u>, not GTK1, for Code::Blocks to be operational.

You do not need to Compile wxWidgets if your distribution has wxGTK 2.8 and wxGTK 2.8-dev package available. A quick search for "wxGTK" through your respective package manager should show bring up the needed packages. After you have installed successfully you can moving on the the Installing Code::Blocks portion. If you are using Ubuntu and have installed the wxGTK package, you must also have the dev version as well as the "wx-common" package in order to successfully compile Code::Blocks.

All the instructions below, assume an existing directory named <tt>~/devel</tt>. If you 'll be using a different one, adjust the path to match.
As a first step create this directory:

<pre>mkdir ~/devel</pre>

===wxGTK installation===

====Getting wxGTK====

Visit the [http://www.wxwidgets.org wxWidgets web site]. Click the "Download" button at the top of the page. Under wxWidgets 2.8.7 downloads, select wxGTK. Save the file in <tt>~/devel</tt>.

====Uncompressing the wxGTK sources====

After the download finishes, switch to <tt>~/devel</tt>:

<pre>cd ~/devel</pre>

Now, untar the wxGTK sources:

<pre>tar zxf wxGTK-2.8.7.tar.gz</pre>

Switch to the wxGTK directory

<pre>cd wxGTK-2.8.7</pre>

====wxWidgets build====

Here we will create a seperate build directory instead of building from the src directory, so that we can easily rebuild with different options (unicode / ansi, monolithic / many libs, etc).

The documentation says the default is for gtk2 to use unicode and wx > 2.5 to build as a monolithic library. This doesn't appear to be the case, so these flags are passed to configure.

mkdir build_gtk2_shared_monolithic_unicode
cd build_gtk2_shared_monolithic_unicode
../configure --prefix=/opt/wx/2.8 \
--enable-xrc \
--enable-monolithic \
--enable-unicode
make
su
make install
exit

Add /opt/wx/2.8/bin to the PATH (if you're shell is bash then edit /etc/profile or ~/.bash_profile)
(On Suse 10.1 edit /etc/profile.local, it will only be available after a new login). an example PATH
export PATH=/usr/bin:/opt/wx/2.8/bin:$PATH

'''Note:''' On Ubuntu Hoary it was necessary to check "Run command as login shell"
in the gnome-terminal profile-settings, otherwise the PATH changes are not available in a gnome-terminal window.

add /opt/wx/2.8/lib to /etc/ld.so.conf (nano /etc/ld.so.conf)
then run:
ldconfig
source /etc/profile

That's it. Now the linker will look in /opt/wx/2.8/lib for wx libraries and you will have a monolithic shared library unicode build.

To check that things are working, type:
wx-config --prefix
which should give you /opt/wx/2.8
wx-config --libs
which should have at least
-L/opt/wx/2.8/lib -lwx_gtk2-2.8
but can contain other flags as well.
which wx-config
should return /opt/wx/2.8/bin/wx-config

===Code::Blocks installation===

====Downloading Code::Blocks====

You can get Code::Blocks source code in one way:
* Get the latest sources from the SVN repository.
This method is described below.

=====Getting the latest sources from SVN=====
'''IMPORTANT NOTICE: The Sourceforge CVS is no longer used although it still exists'''

Enter your development directory:
<pre>cd ~/devel</pre>

Then checkout the source using one of [https://www.codeblocks.org/downloads/7 these] methods.

This will create the directory <tt>trunk</tt>.
Change to the source code directory, by issuing the following command:

<pre>cd trunk</pre>

====Building Code::Blocks SVN====
If you are a Gentoo user, please see [[Compiling_Code::Blocks_in_Gentoo]].

Before beginning, it is often a good idea to check you have recent versions of autoconf and automake - repositories versions are not always recent enough. (if you do not have automake, then you will get "cannot find aclocal" error).

If you're compiling the svn trunk versions of CodeBlocks (or future versions) then the unix build has switched to autotools. So first build wxWidgets as described above and then build CodeBlocks as follows:

./bootstrap

This sets up the configure script and its dependencies. It only needs to be run once (after downloading the source from svn). '''If you get errors like:'''
aclocal:configure.in:61: warning: macro `AM_OPTIONS_WXCONFIG' not found in library
Then aclocal is having trouble finding the wxWidgets .m4 files. You can do one of two things:
To just get bootstrap to find the path this time do:

<pre>export ACLOCAL_FLAGS="-I `wx-config --prefix`/share/aclocal"</pre> 

To change the aclocal search path more permanently do:
echo `wx-config --prefix`/share/aclocal >> /usr/share/aclocal/dirlist
Then aclocal will also search somewhere like /opt/wx/2.6/share/aclocal

'''Note for Ubuntu users:''' The above is not the correct way to fix the AM_* errors. Rather, you only need to install the package named "wx-common" (Universe repository).

If you get something like
The usual way to define `LIBTOOL' is to add `AC_PROG_LIBTOOL'

it can be solved by something like: (adapt path, use `wx-config --prefix` is necessary)

ACLOCAL_FLAGS="-I /usr/share/aclocal" ./bootstrap

(*Note// '''If you run ./bootstrap and get errors like''':
: bad interpreter: File not found
then there exists a problem with DOS line-endings. i had this error after i tried to build a codeblocks from sources which were checked out with cvs on a windows machine. After i checked out a fresh copy of codeblocks from cvs under Ubuntu linux (see above topic: Downloading the latest source package fom SVN), all errors were gone.
//tiwag 051008*)<br>
Or, instead of downloading from SVN, you might consider using the little command line tool dos2unix, which normally comes with most distributions. //lizzarddude060103
<br>
If configure aborts with some unspecific error message(".infig.status: error: cannot find input file: Makefile"), you might consider also running
dos2unix bootstrap acinclude.m4 codeblocks.pc.in configure.in Makefile.am
before running bootstrap

Once you've run the bootstrap script, installing is as simple as:
./configure
make
make install

If you have multiple versions of wxWidgets installed or kept them inplace, you can use
./configure --with-wx-config=/path/to/wx-config

To uninstall you can later run:
make uninstall

If you want to recompile everything, first run:
make clean
make distclean
make clean-bin
make clean-zipfiles
and then follow the above sequence for installing.

By default, CodeBlocks will install to /usr/local. If you want it in its own tree (so you can have multiple versions of CodeBlocks, each in its own subdirectory of /opt) replace the above ./configure command with:
./configure --prefix=/opt/codeblocks-svn
or similar. Then you can later install a different build like:
./configure --prefix=/opt/codeblocks2-svn
followed by 'make && make install' as usual.

By default, CodeBlocks will not compile the contributed plugins from SVN. If you want to compile / install them too, replace the above ./configure command with:
./configure --with-contrib-plugins=all
followed by 'make && make install' as usual.

To see a list of other options available for configuring the build of CodeBlocks do:
./configure --help

To compile under gentoo, use
./configure --with-wx-config=wx-config-2.8

====Resolving issues with Code::Blocks SVN====

When running Code::Blocks after the installation it might happen, that the system complains:
codeblocks: error while loading shared libraries: libcodeblocks.so.0: cannot open shared object file: No such file or directory
In that case make sure the library path where the Code::Blocks libraries where installed into is "known" to the system. For example: On Ubuntu using a default build process on a clean system will install the Code::Blocks executables to /use/local/bin and the libraries to /usr/local/lib. The latter is usually not known to a "clean" Ubuntu system. To add it to the search path for libraries do the following (as root / using sudo respectively):
Add the following line to the file /etc/ld.so.conf:
/usr/local/lib
...and run:
ldconfig
That's it - Code::Blocks should now work just fine as all libraries are being found.