Basic Tutorial

Introduction and other things

This document will try to help you get started with the Code::Blocks IDE. (IDE stands for Integrated Development Environment. It means that it is a program to help you with creating software, but remember: it only helps, by giving you useful tools and make easier to use them than the command line, it is not a compiler or a debugger! It just helps to use them.) As English is not my native language, there will probably be many "translation" errors (not really translation, because I am writing it in English directly...) so do not hesitate to give me reports on the forum! (/index.php/topic,15076.msg101500.html#msg101500) If you think something is missing, you need enhancement, please, say it too. I can't make a complete tutorial, because I use this tool from many times, and will probably forget some stuff I'm using every day.

And last, but not least, it's not a tutorial about programming. If you need something like that, please consider searching on the web. As a good hint, I will say www.cplusplus.com, which is my favorite site for searching C++'s easy to read documentation. It has some tutorials too.

Be warned: I am using a nightly build of Code::Blocks, because they are not so hard to install, include many improvements, and are stable enough for use on a daily basis. At least, stable enough for me. So by using the official but old version of Code::Blocks (10.05: more than a year at the moment I am writing those lines). It implies that some menus may have changed and you could have to search for something near my words, not exactly my words. Remember: if you want to write programs, you will need to be able to learn by yourself. It's more important than being able to use a technology, because all technologies can evolve! (But I will try to be as accurate as I can).

At last, don't hesitate to try something that is not specified here, I think doing is better than reading. We learn more with a fail, than with a success. If you mess up your Code::Blocks' install, it's not a problem, just remove configuration files and reinstall it. (configuration files are in you user directory. It means in "%UserProfile%" under windows and in "~/" for unix likes. Remember that they can be hidden, so it is possible you need to disable the hiding feature of your file manager.)

Installing Code::Blocks

First, you have to install Code::Blocks. If you are using windows and preparing yourself for your first step in development, I recommend you to install the version bundled with mingw. Else (or if you don't mind this advice), you can read some articles about installing Code::Blocks: Installing Code::Blocks

First start

First steps and basic customizations

At first startup, you will have a splash screen with the logo of CodeBlocks (later in this text, I will say "C::B". You could see the "CB" word in some places too). Just wait a bit and C::B will ask you what compiler you have on your computer. If you use Microsoft Windows system, and have installed C::B from the installer I recommended at the beginning of this article, you should have the mingw compiler detected. If you are with a Linux distribution, you probably have the GNU GCC Compiler detected.

When you validate, the first compiler detected will be set as default. You could prefer to select another for your common use, just select it then click on "Set as default". If there is no compiler detected, then install one; using an IDE without compiler is not very useful.

When you have validated this first dialog, you will have C::B with a tip of the day. Read these tips, they can give some useful hints, as this document don't pretend to say everything about C::B. (But I'll try to do my best...) Close it when you have read enough :). If you don't want to have it each time you run C::B, just click on "Show tips at startup"

Second action shall be to rearrange all those tool-bars. There is also one floating... By defaults, they are enabled, but you can remove the by clicking on "View", then go into "Toolbars" and then remove the checked ones (ok, just the ones you think are boring). You can also just move them, if you think you'll need them. (In this document, I will use the menu names and write the entry each time) I recommend you to disable them all. In fact, the faster you learn to search in the menus, the faster you'll use C::B. And it can help you learn shortcuts... The mouse will often slow you. (about that: as in many applications, ALT+'underlined letter' will often be like a click on the button/menu)

Some more personal configuration

This section just contains some tips I think good. In fact, if you want to go quickly to your first project, just jump to next section...

I've learned some tips, and have adopted some habits about some settings disabled by default. I will give you some of them as well as highlight some functionalities by the setting options. This is often a good way to start learn how to use software in detail, but never (or only in bad software) mandatory:

Environment

• In "General Settings" for Debian's users, I recommend to set "Shell to run commands in:" as "x-terminal-emulator". It will allow C::B to use the terminal emulator you

installed. (I don't like xterm...)

• In "View" for people who prefer to have their IDE internationalized, check "internationalization" and give what it need. I guess it is a directory with .po files, but you will

have to find/make yourself the translations (there is a French one here: /index.php/topic,1022.165.html but I never used it... If someone knows more, about any translations and/or how to enable it, please give me the procedure and links, I'll integrate them here, or modify yourself this page)

• In "Disabled Dialogs" you will see all dialogs you have disabled, it will allow you to re enable them.

• "Environment variables" will allow you to modify C::B's variables, and define them in sets. It allows easier management of external libraries. (and so, make your projects easier to move from a computer to another)

• "ToDo list" one of my favorite plug-ins. This menu allows you to include it in the bottom panel. This plug-in will parse source files (you can choose the scope: actual file, actual project, or whole workspace) and tell you where there are some special comments and what they say, allowing you to never forget to enhance, remove or finish a piece of code. You just have to write a comment with a special syntax (or use the contextual menu in the editor). If you don't like it, or if you are working on a big project, you can disable the auto-refresh here.

• "Thread Search" will allow you to set-up an advanced search. This search will search (obvious, isn't it?) in a set of file (it can be all opened files, some target files, the project's files, the workspace' files or files in a directory) for a text you want (well, a text or a regular expression pattern, also known as "Regex"). The power of this plug-in, is that it store results in the bottom panel (yes, again...) and allows you to search in all occurrences what you want, because it gives you a thumbnail of what is around the thing it has found.

• "Help files" Another extremely useful plug-in! Here you can add help files into C::B's context menu. It will allow you, for example, to select a word, press "F1" and to have a window pop-up with the content of your help about that word. I've tested it with chm files (help files of Windows), never tried man or html, but it seems it works too.

Editor

• "General Settings": here are many useful things. You can modify the size of a tabulation, and specify if you prefer it to generate spaces or TAB characters (the advantage of TAB is that when you use arrows, you move faster with tabs than spaces).

  You can also enable/disable some customizations about indentation. Personally, I don't like the brace completion, but I like indentation guides, it make it easier to know, what block of code you are in.

  The last thing I modified here was the "Highlight line under caret". Useful to know exactly which line you are on, if your caret is far from the beginning or vice versa.

• "Margin and caret" here you can gain some place with the line numbers. A useful option is the "Dynamic setting" at first line. It will allow the width to be optimal. Just enough to write the full line number, not less, not more: no waste of space and a nice look about your position!

  Next is the "Right margin". Not so useful if you work alone on a wide screen, but when you work in some project with other people, it can happen that a coding convention forbids you to have more that, for example, 80 char width. This setting helps you with that. (this rule can be useful for people who don't like word wrap or scrolling, and can sometimes work on a portable computer, during holidays or travels.)

  There are also some options about advanced selections: "Enable virtual space" which will allow you to have something like a paper, you can place your caret everywhere you want, without placing any spaces.

  And the "Allow multiple selections" with the sub option "Enable typing (and deleting) in multiple selections simultaneously", to be able to alter many lines with only one type. Useful when you use some copy/paste or are writing some switch cases...

• "Syntax highlighting" will allow you to use C::B for another language, and/or customize some highlights. (On some screens (like my notebook), there are some comments which are impossible to read due to low contrast. The solution to this problem is here!)
• "Default code" will allow you to automatically insert some code when C::B generate a file (like a class or header). Can be used, for example, to insert licensing (commonly used when you look into GPLed sources)
• "Incremental search settings" this menu allows you to customize the incremental searches. What is it? Incremental searches are searches which highlight the results. You have something like that in some web browsers, for example. When you type, the software searches for what you are writing and highlights it to avoid you passing through it without seeing.
• "DoxyBlocks" well, another very useful plug-in. This one allow C::B to generate comments for doxygen, and drives doxygen to generate the documentation about your code (doxygen is a free software). I recommend you to use this if you don't actually, because a lack of comments often will give you many hours of useless work.

  This setting panel is like a simplified doxygen GUI.

• "Code completion": one of the main features of an IDE. The code completion allows you to "summon" the rest of the word you are typing, or give you some nice hints, because programmers are not like computers: we don't have random access to all our memory, or don't want to remember everything about each piece of code we (or someone else) wrote. So Code Completion, or CC helps us. Here are some options to customize it. (I think it is easy to understand what they mean, so I will not explain them, except for "Keywords sets to additionally include" which is used to adds all the words defined in the "Syntax highlighting" "Keywords..." sets (the ones which are selected, that is) to the list of words CC suggests from.)
• "Keyboard shortcuts" can be useful, if, like me, you don't really like to rub your desktop with your mouse.
• "Source formatter" also known as AStyle. This plug-in "simply" reformats your code. If you take some code from someone else, or produced by a code generator, just run this plug-in to have your code formatted to your preferences. Well, you could need to setup them before, obviously. But the most common styles are already implemented, so you'll probably just have to select one of them and go!
• "Browse tracker" this plug-in allow you to navigate quickly in your code thanks to some keyboard shortcuts.
• "WxSmith Settings" this is the RAD plug-in of C::B, allowing to quickly draw a wxWidget application. Some nice (for me) customizations here are "add new items continuously", setting "proportion" to 0 and enabling "expand". But these are my preferences...

Compiler

• Global compiler settings: Here are some options redundant with project's and target's one: Compiler settings, Linker settings and Search directories. I will skip them for now and jump to the useful ones: Toolchain executables, Custom variables, Build options, Other settings.
  • Toolchain executables: it allow you to specify to CB where it have to search for compilation binaries, if it didn't find them automatically.
  • Custom variables
  • Build options: There are some very useful options to make the compilation quicker:
    • Number of build process: I recommend you to set it to the same number of cores your processor have. Il will allow your compiler to compile more than one file at a time. With a dual core, it can divide compilation time per almost 2! (Almost, because some time is spent by a core to say to the other what he have to do, and because some steps must be made in a specific order. This is a good reason to #include the less files you can in headers, and set those #includes in the source files.)
  • Other settings
    • Compiler logging: allow to have a full log of what compiler do. It is less readable, but give all informations that can be needed to understand why something don't compile/link, or by people to help you. It is highly recommended to enable it before asking something on a forum.
    • Compiler output to be ignored: this function will allow you to remove some annoying warnings, which come from an external library. It may be useful to fasten the compilation time, because showing those warning can slow CB when you have many of them.

      NOTE: there is an "Advanced options..." button here. As the dialog say when you click on it, you can damage CB build system. As I never tried to play with those settings, I will not speak more about this.

• Profiler settings
• Batch Builds

Debugger

(for the debug nightly only, but it will merged ASAP. I think it is stable enough to be used) This dialog box do not have so many options, and they could change quickly, as the debugger plugin is under refactor. so I will skip it.

Global variables

CB have an internal variable system, used to customize project's and target's settings, making them easily portable, on another OS or just another computer. To use them, use "$(#VAR_NAME)" where VAR_NAME is the name you used. To use any of its subparts, use VAR_NAME.SUBPART. By example: "$(#sdl.include)" use the "include" part of the "sdl" global variable. You can see them as C structures, accessed when CB find something in $() and the access to their members is made with the . (dot). Note that the base member can be accessed without using the subpart syntax. Here you can choose a set of variables to use. In this set, you can easily add/remove/modify existing variables, variables which contain 4 main fields:

• base: contain the "root" path, used by the 3 other main fields if you fill them with relative paths.
• include: contain the path, absolute or relative to "base", where include files are.
• lib contain the path, absolute or relative to "base", where lib files are.
• obj contain the path, absolute or relative to "base", where obj files are.

2 other fields, but not as often used than the 4 above, are

• cflags: contain additional compilation flags?
• lflags: contain additional linker flags?

There are also 7 custom fields, where you set the name of the subpart, and define it's value.

Scripting

I don't know how it work. Will be made when I'll have time to spent to learn it.

WORK IN PROGRESS

Creating the first project

Introduction about how C::B manage projects

There are 3 levels of project management in C::B:

• the workspace, contains projects, and will allow you to manage their inter-dependencies. It is the highest unit, and you can only open one at a time.
• the project, contains targets. It's the main unit, allowing you to write that it depends on external libraries or what options it will need to compile in all systems. You

can open all projects you want at same time.

• the target, which allows you to give precise options your project will need to compile under a specific configuration, like a debug or another OS. A project can have as many

targets as you need.

Workspaces

C::B is able to open multiple projects at the same time. The layer containing those projects is named the "workspace". They mainly allow you to "bind" projects together. There are no specific options in it, so presentations will be quick:

• if you right click on its icon in the "management" panel, a contextual menu will appear. Entries are very easy to understand: you can save it, rename it, build all projects

it contains, clear all projects it contains. <<< I never use those options, so I don't know if a specific target is used, or if it manages all targets... >>>

• when you go into "Project"->"Properties" (or do a right click on a project) there is a button at the bottom of the window, named "Project's Dependencies". If you click on

it, a window will appear, showing for the selected project (can be changed by clicking on the choice control) and a list of all other projects in the workspace. To tell C::B that the selected one depends of another, just check the case on the side of the desired project. If you select a project which depends, directly or not, on the one selected, C::B will warn you and refuse to check. The utility of dependencies is that when you will build the active project (this is what C::B names the selected one), C::B will also build every project on which this project depends. It can seem useless when you only work on one or two projects, like the examples I used in introduction, but imagine this: You have a client, depending on 2 libraries, a server, depending on the first library of the client, and another. Each of those projects use units test, and so depends on them to know when you accidentally introduce regressions. So you have a client which depends on 9 projects (the server, the 3 libraries, and the 5 unit testing projects), a server with a fewer dependencies (you can remove the library specific to the client, and their units testing projects) and libraries. And maybe you are the only one on the development of everything (I hope for you) so when someone modifies something you have to verify that all your stuff is up to date. Using this dependency system will allow you to just make a build on the project you have modified; C::B will manage all its dependencies. That's not all; C::B will also manage run directories to allow you to run your application, finding dynamic linked libraries automatically. You don't have to copy/paste the files in the execution directory. Easy and quick.

Projects

Generalities

This is the next level of C::B's project's management stuff, and the main one, with the more options.

• "Project"->"Build Options...": This option will be explained in the next section: #Targets.
• "Project"->"Properties" (right click on a project and click on properties): this will show you a window with many tabs, the first one having two buttons at its bottom: one

allows you to manage project's dependencies, and which has already been described, and the other allows you to specify build options. The second one will be explained in the next section: #Targets.

Here is a list of tabs, and a quick explanation of what they allow for those I know. I will give more explanation of them in sub-sections when it is needed (and when I have knowledge, obviously). For tabs I never used, I will put a "(?)" at the end of explanation, to allow readers to know that information is not verified, and encouraging them to complete this document.

• Project Settings
• Build Targets
• Build Scripts
• Notes
• EnvVars Options
• C/C++ parser options
• Debugger : (?) allows you to specify directories in which debugger can find information about source code, for libraries that provide it. It can configure remote debugging
• Libraries : (?) will manage libraries you use in this project. I never used it, but it seem it allow to manage libraries you use automatically.

Targets

The target is the smallest build unit in C::B. ( I didn't say that it is the smallest compilation unit, C::B is able to compile files separately. Or, to be more accurate, is able to tell to the compiler to compile files separately. Never forget that C::B is NOT a compiler or debugger, only a tool to help you in dealing with these kinds of software.)

• I will not talk about the client/server methods, as I never had the chance of developing such software architecture.