Skip to content

Linux Daily

Daily usage of linux, raw style

Step two in The Odyssey – From Nothing to the Ubuntu Software Center.

At this point the VM is all set up and ready to go. All we need is an application.

Linux has several toolkits and frameworks to program graphical applications. Some are bad, some are beyond shit, but at least one of them is top notch – Qt.

Qt is a C++ framework created by vikings from the grim and frostbitten lands of Norway, so you know that shit is for real. It is the only Linux GUI framework that packs an IDE, and a fantastic one for that matter. If you’re interested in python, java or any other garbage collected non-sense I advise you to skip this step and jump to packaging. C++ is for high-octane engineers with a firm grasp of memory management and pure virtual classes. Consider yourself warned.

Now, developing applications isn’t just about frameworks and programming languages. Oh no. There’s source control, source documentation, debugging, unit testing, memory debugging, etc. Yeah, and I mean it: etc! Hopefully we’ll cover most of these concepts till the end of the series. For starters we’ll cover creating a basic project in Qt, using Git for source control, publishing code to Github and licensing.

With me steering the ship, what’s to worry? On with it!

1. Set Up Git

Alright, VM ready to go, all is good but we ain’t going anywhere without Git installed. Don’t know what Git is? Take the crash course and you’ll be up to speed within the hour. If you don’t feel like it don’t worry, I’ll cover the basics.

Install

Git is in the officials reps, so installing is just a matter of:

sudo apt-get install git-core

Configure

Git has some basic configurations you need to setup before you start source controlling like a pro. Still at the terminal, this is my preferred configuration

git config --global user.name "Anonymous Bloke"
git config --global user.email anonymous@bloke.com
git config --global core.editor vim
git config --global merge.tool vimdiff
#List these configurations
git config --list

Git is now officially ready to go.

2. Start a new Qt Project

Install

Qt’s IDE is called Qt Creator, and it’s also in the official reps:

sudo apt-get install qtcreator

The Qt Creator interface. You'll be looking at this for a while.

This should install QtCreator 2.4.0 and pull Qt 4.7.4 as a dependency. Start it and you should see a window much like the one in the screenshot.

What are we looking at?

Well, there’s the sidebar on the left. This is the major anchor in the interface. From here we can access the code in Edit,  we can design a UI by dragging and dropping elements in Design, GDB can be used in debug, projects list recent projects, Analyze is new so I’m not sure what it does to be honest, and finally, Help is for other people.

On the lower left, we have a couple of icons. First one is to configure the current build, the play button runs the program, bellow it is the button to debug a program, and the hammer thing is to just build and not run.

Humpf, all done. Got that? Ok, now let’s create a new project in fil…

Oh no you don’t! Decide on licensing first!

Nope, not kidding! The first thing we do when creating a new project is think about licensing. Each source file should have a header with the copyright declaration, where you, the copyright holder, inform the reader about the deadly consequences of stealing your code. I recommend you use the GPL V3 because although I find Richard Stallman to be quite a weird character, I do not doubt for a single second that he’s doing his best to protect our freedoms.

All code released under the GPLV3 should have a short notice on every source file. My template notice is available here, and I’d like to call your attention to the first 3 lines:

/*
 * %FILENAME% - Math Machine
 * Copyright (C) %YEAR% Anonymous Bloke

So, the project is gonna be called Math Machine and the copyright is for Anonymous Bloke, which you should change to your own name. Qt Creator will do all the work and automatically append this notice to your source files. The %FILENAME% and %YEAR% keywords will be interpreted by Creator and changed accordingly (you can see some more of these here if you need a more elaborate copyright notice).

To make use of this notice, define the file as the license template in Tools/Options/C++/File Naming/License template.

With the license template in place, we can finally create our project by hitting File/New File or Project. There, select Qt Widget Project/Qt Gui Application.

In the wizard there’s a couple of things you need to check.

First off, our project is gonna be called “MathMachine” and I suggest you put it in a new folder called developer in Documents. Just to keep shit organized.

No math in the machine just yet, but hey, it's a start!

Second, we’re gonna be brutal and uncheck Generate form in Class Information. In this example we won’t need it.

Lastly, in Project Management be sure to add this project to git instead of the default <None>.

Boom! We have a project. Standard Qt boilerplate, nothing fancy. You can even run it by pressing Ctrl-R. The result looks something like the picture to the right – an empty window called MainWindow. Sweet.

Your first commit

Awesome.

First things first, we commit! In Tools/Git/Commit. you should do something like in the screenshot.

Now, there’s a couple of things we need to do to push our source control all the way up to 11. First, right-click in main.cpp and choose “Open Terminal Here”. Then run

git status

Which should say

# On branch master
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#    MathMachine.pro.user
nothing added to commit but untracked files present (use "git add" to track)

There’s a leftover file. Could be better. These .user files are Qt Creator instance specific – we should flat out ignore them. Let’s create and source control a .gitignore file – we don’t want anybody dealing with this .user business.

echo "*.user" > .gitignore
git add .gitignore
git commit

Your default editor will show up. There’s an unwritten rule that commits should have a short title and a brief description of the commit separated by a blank line. Like this.

Ignore *.user

Added .gitignore with QtCreator *.user files.

Save and exit. Now, if we run git status we’ll see

# On branch master
nothing to commit (working directory clean)

Which is much nicer. No MOM I don’t have OCD, don’t embarrass me in front of my friends!, I HATE IT when you do that, I just like things need und tidy, what’s wrong wit-

3. Prepare for public debut

Oh my! Who said anything about going public?! Don’t you just love surprises?! We’re gonna release the software as is!

According to the GNU standard, free software releases should come with a bunch of all caps files.

COPYING

All GPL code should have, in addition to the copyright header, a COPYING file with a transcript of the GPL. It says so right here. So, open a terminal in the project root folder once more (right click on main.cpp, open terminal here) and

wget http://www.gnu.org/licenses/gpl.txt
mv gpl.txt COPYING

Now, this is just a personal preference of mine, but I like to see this file in the project tree. You can right click on your project (the top level of the tree) and choose Add existing file to add the COPYING file and say Yes to add it to git. You know, just to keep shit organized.

README

A classic. Instead of add existing file, this time select ADD NEW and then General/Text file. Qt will insist upon the .txt, and you shall insist in renaming it by right-click on the file and selecting rename.

There’s a good standard for writing README files. It’s called AsciiDoc and it’s a good idea to use it. By following the syntax, we can convert our README to a webpage, a pdf, etc. Here’s a nice README for our program

Math Machine README
===================
Anonymous Bloke <anonymous@bloke.com>
:website: http://linuxd.wordpress.com

Math Machine
------------

Math Machine is part of "The Odyssey", a series of guides on how to
properly distribute a free software application. It does two things
and two things only:

- Start.
- Exit.

I know.

=== Installation

Please refer to the INSTALL file

Simple.

INSTALL

We’ll do exactly the same thing with the INSTALL file. Just to keep shit organized.

Math Machine INSTALL
===================
Anonymous Bloke <anonymous@bloke.com>
:website: http://linuxd.wordpress.com

Math Machine cannot be installed. Yet.
However, it can compile to a binary by doing

qmake
make

 :-)

Done. Now commit like before, and we’re golden!

4. Set up GitHub

That’s right, we’re gonna go with the latest trend. GitHub is DOPE.

Register

Head over to www.github.com and register an account. Do remember to register with the same e-mail  from your git configuration (“anonymous@bloke.com” in this example)

Create an SSH Key

GitHub forces you to use a sweet SSH setup. In order to have write access to the repo, and hence be able to push, a local ssh key has to be created and registered with the website. Each machine should have a different ssh key, so you might want to repeat this process from the Ubuntu 10.04 VM.

Head over to the terminal. Again, mind the e-mail address.

ssh-keygen -t rsa -C "anonymous@bloke.com"

Add your SSH Key to GitHub

On the GitHub site click Account Settings>SSH Public Keys>Add another public key. The public key is

cat ~/.ssh/id_rsa.pub

Holler!

ssh -T git@github.com

Which should reply

The authenticity of host 'github.com (207.97.227.239)' can't be established.
RSA key fingerprint is 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'github.com,207.97.227.239' (RSA) to the list of known hosts.
Hi bloke! You've successfully authenticated, but GitHub does not provide shell access.

Totally not a calculator.

Create a new repository

For our example, create a new repository called MATH MACHINE. GitHub will present instructions on how to add this new repo.

5. Now, Push!

You could add the repo to the local git like in the GitHub instructions

git remote add origin git@github.com:bloke/Math-Machine.git

Or use QtCreator’s GUI Tools/Git/Remotes

Name: origin
URL: git@github.com:bloke/Math-Machine.git

Choose one, but you have to go to the terminal anyway for the FINAL PUSH.

git push origin master

Really! It’s done! Click continue on the instructions page on GitHub. And see your baby.

Notice that now, everytime we hit Tools/Git/Push in Qt Creator it will push the master to origin (meaning our code changes to GitHub). Do it in the terminal, via menus, you decide.

You probably noticed the README doesn’t look too good on the GitHub repo page. If you rename it to README.asciidoc it will render great. If you’ve reached this far, you probably know how to do this right? In QtCreator

  1. Rename README to README.ascii by right clicking on the file and selecting RENAME
  2. Commit!
  3. Push!

Alright, first change! Pretty sweet, hum?

The end

Dude, what a ride! Next up:

  • Find out what Math Machine is actually supposed to do! Is it a calculator? Does it do math? Is it even a machine? Who knows! not me!
  • Source documentation with Doxygen
  • Unit Testing with QtTest
  • Memory debugging with valgrind
  • … And more!

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: