Difference between revisions of "Basic Tutorial"

From Code::Blocks
(integrate new alpha fixes (sorry for the long time))
Line 116: Line 116:
 
*: This setting panel is like a simplified doxygen GUI.
 
*: 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
+
* "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.)
coders are not machines: we don't have random access to all our memory, or don't want to remember everything about each piece of code we wrote. So Code completion, or CC helps
 
us. Here are some options to customize it. I like to enable the "Auto-select, if only one match", and removing the "automatically launch when typed # letters" because I use 
 
CTRL+SPACE to invoke the feature. For "Keywords sets to additionally include", I have to admit I don't know what it mean, so I let it by default.<!-- This 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.
 
* "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   
 
* "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   
plugin to have your code formatted to your preferences. Well, you need to setup them before, obviously. But the most common styles are already implemented, so you'll probably   
+
plug-in to have your code formatted to your preferences. Well, you 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!
 
just have to select one of them and go!
  
Line 132: Line 128:
 
* "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",   
 
* "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 options...
 
setting "proportion" to 0 and enabling "expand". But these are my options...
 
  
 
= WORK IN PROGRESS =
 
= WORK IN PROGRESS =

Revision as of 08:23, 22 September 2011


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 win. 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)

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 guys 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 (I just know there is a French one, but don't remember where. 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)

  • 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.
  • "ToDo list" one of my favorite plug-ins. This menu allows you to include it in the bottom panel. This plug-in will parse something (you can choose: 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 (you always know what codeblocks you are in, don't you?).

  • 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

(lines are very long and your caret is at its beginning)

  • "Margin and caret" here you can gain some place with the line numbers. A useful option (really, for those as useful as this one, I don't know why they are not default... but

C::B's dev have so many work and private life, but took time to gave us those nice options so it's ok, don't you agree?) 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 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 (common

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

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.