return;

C programming guide

Comprehensive setup

This is a comprehensive version of the setup process with proper explanations for things, to make sure you're left with as full of an understanding as possible.

This page is long because it explains everything, the amount of things we actually need to do is very small. I recommend reading the sanic fast setup first to get an overview of what we actually need to do.

Prerequisite: how to use command line

Before we can even use the compiler, we need to know how to use a command line. You don't have to start "using" it, you just need to understand the basic idea behind it. Feel free to skip this part if you're already familiar with it.

A command line or a console ("CMD" on Windows, "Terminal" on Linux) is a program that lets you talk to your operating system and other programs through text commands instead of clicking on things with a mouse. The reason we need it is because the compiler is a command line program, which means that you can't just click it to use it, you have to start it from the command line and tell it where your code is. That's all you need to do with it though, and we'll create a special file later so we can automate it.

To open the command line:

Windows (CMD): press Win+R, then type cmd into the box.

Linux (Terminal): press Ctrl+Alt+T.

The first thing you type into a command line will be the name of a program. For example if you type "skyrim", the command line will look for skyrim.exe in the current folder and try to start it (you don't need to include the ".exe", but you can if you want.

On the left is the current folder that you're in (on Linux it will also show your username). To see what's in the current folder, type dir on Windows or ls on Linux. To move into a different folder, type cd foldername. To move backwards, type cd ...

In case you wonder, "cd" may in fact be a program somewhere in your computer (though it may also be an inherent part of the command line program), if you replace cd.exe with skyrim.exe then the command line will launch Skyrim every time you try to change the folder. But cd clearly isn't anywhere to be seen so how does it just werk anyway? The command line has some hidden variables, one of which defines different locations to look for programs from. When you install command line programs like ffmpeg, the installer will add a new path to that variable so that your command line can find ffmpeg.exe from anywhere, just like cd. You can create new commands yourself this way and fix issues, look up "PATH variable" if you're interested in it, both Linux and Windows have it.

Linux Unlike Windows, Linux does not search for programs from the current folder, it only looks for them from the PATH variable locations. In order to run a program in the current folder, you need to add ./ before the filename, so rather than typing skyrim, you would type ./skyrim. Linux also does not use .exe as a program file extension, in fact it often doesn't use a file extension at all.

Anything you type after the program name will be sent into the program, and the program will decide what to do with it. The program will also know what folder you're in, so if you type compiler.exe file.c, compiler.exe will most likely assume that file.c is in the same folder that your command line is currently navigated into.

You can type the full path of the program instead of just the program name, for example C:\something\program.exe instead of just program.exe. This way you can access files that are in a different folder than the command line is at, and don't have to modify the PATH variable.
You can put paths into quotes, this can be useful because for example C:\Program Data\something\program.exe will not work since the command line thinks that C:\Program is your program. You can fix it by adding quotes: "C:\Program Data\something\program.exe".

If the program you started on the command line is stuck or waiting for whatever reason, you can forcibly quit it by pressing Ctrl+C. This will be important when you run and test your own program.

Install the compiler

The only program you'll need (besides a text editor) is a compiler. The compiler is just a program file like any other, and is used in the same way as we used cd above. For this guide we'll use a compiler called "GCC", it's one of the most popular C/C++ compilers and has versions for both Windows and Linux.

Windows You'll need to install MingW (which includes GCC):
https://sourceforge.net/projects/mingw/

Alternately, you can get an unofficial version from here without having to enable javascript:
https://nuwen.net/mingw.html (mingw-XXX-without-git.exe)

Linux You might already have GCC. If not you can install it by typing sudo apt install gcc into the command line.

On the command line, type gcc --version to test if it works, you should get some information about the GCC version. If it doesn't work, then your command line can't find gcc.exe, you can either add the location to your PATH variable (see previous section), or type the full path into the file instead of just gcc.

Make a test program

Paste the following code into a new file for now (the code will be explained in the programming part of this guide).

#include <stdio.h>
int main () {
	printf("Bag of biscuits\n");
	return 0;
}

Save the file as "main.c". The filename doesn't really matter, but I recommend always naming it "main" so you know which file the program starts from.

On a command line, navigate to the folder where you saved main.c, and type gcc main.c -o testprogram.

[-o] means that the next part of your command is going to be an output file name, which the above defines as "testprogram".

The program should have been created, run it by typing testprogram on Windows, or ./testprogram on Linux. You should see "Bag of biscuits" being printed onto the command line.

Tip: you can press up/down arrow keys to browse previous commands in the command line, so you don't have to retype them from scratch every time.

Linux While on Windows you can now just click your program .exe to run it, Linux doesn't want you to just run programs like that. I don't know exactly how to do it on Linux, but you can kind of do it by creating a launcher file.

Click here for instructions.

Make a new text file called "testprogram.desktop" and type this into it:

[Desktop Entry]
Name=Test Program
Exec=/full/path/to/your/program/testprogram
Terminal=true
Type=Application

The Exec field must have the actual path into your program. You can think of the .desktop file as a shortcut icon, you can move it where ever you want. However, if you move your program, the shortcut breaks.

You can now double click the shortcut to start your program.

Note that you can't release a program like this to other people, you don't know where they will put the files so you can't know what to type into the Exec field. In Linux you're supposed to use automated methods for installing programs and use application menus or the command line to start them.

There are some tools that let you create Windows-like executables, but they require additional setup. Krita is one of the biggest programs who use it, look into "AppImage" or "Flatpak" if you're interested.

Automating the compile with a script file

Compiling can get annoying because the commands may get long and have multiple parts or even settings on them. So we're going to make a file that allows you to define command line commands, and execute them all simply by running that file, that way you don't have to remember how to compile the program or bother typing so much.

Windows Create a new file called "build.bat" and save it in the same folder as your main.c file. Add the following text into it:

@ECHO OFF
gcc main.c -o testprogram
testprogram

The first line will will prevent the .bat file from spamming your command line.
The second line will compile your program.
The third line will run the program.

Now instead of typing the compiler command in the command line yourself, you can simply type build to compile and run your program. ".bat" can be omitted just like ".exe", but you can type build.bat if you want. You can also just click the file to compile and run, though the window will immediately close because our current program just runs to the end and quits.

Linux Create a new file called "build.sh" and save it in the same folder as your main.c file. Add the following text into it:

#!/bin/sh
gcc main.c -o testprogram
./testprogram

On the command line, navigate to the folder and type chmod u+x build.sh. chmod lets you modify file permissions, u+x sets the file to be executable, this is necessary because Linux won't let you run files without defining them as executable first. The compiler will make your program executable so you won't have to do it.

Think of u+x as giving "Users" (normal user, as in you don't need to be an administrator) the permission to "eXecute" the file.

The first line says that this is a "shell script", I'm not sure why it's necessary but it is.
The second line will compile your program.
The third line will run the program.

Now instead of typing the compiler command in the command line yourself, you can simply type ./build.sh to compile and run your program.

However there's a problem with this file: if there's an error in your code and the compiler fails to compile it, the build script won't care and continues anyway, and tries to run a previously compiled version of your program. We can fix that by adding a condition:

Windows Change the build.bat like this:

@ECHO OFF
gcc main.c -o testprogram   && (
	testprogram
)

Linux Change the build.sh like this:

#!/bin/sh
if   gcc main.c -o testprogram   ; then
	./testprogram
fi

Now if the compile fails, the program won't be run.

Some people prefer to run the program separately, in that case you can just remove the part that runs the program. Feel free to experiment and modify the file however you want, but be careful because you can cause problems if you use the wrong commands. For example rm seems like an innocent thing to type into the command line, but it is actually a command on Linux that deletes files.

Optional: start the build script from your text editor

If you're using a good text editor, you can run the build file with a keyboard shortcut. That way you can just press a key combo to compile and run your program without having to switch to a different window.

Click to view instructions.

Sublime Text
  1. Tools > Build System > New Build System...
  2. Replace the whole text with { "cmd": ["build.bat"] } on Windows, or { "cmd": ["./build.sh"] } on Linux
  3. Save in the default folder.
  4. Tools > Build System > select the build system you just created

Now you can just press Ctrl+B to build the program.

However, the program will run inside Sublime Text and possibly get stuck, so we need to make a small change to the build script in order to run the program separately:

Windows Change the testprogram line into start testprogram:

@ECHO OFF
gcc main.c -o testprogram   && (
	start testprogram
)

Linux Instead of just running the file with ./testprogram, you will need to start a new terminal and send "./testprogram" into it. The way to do this depends on the Linux distribution, but on Ubuntu and related distros you can change it to: gnome-terminal -- ./testprogram

Note that since the build system just calls "build.bat", you must be viewing a file from the same folder as your build.bat when you press Ctrl+B. There's ways around this but it requires you to manage projects, there's better guides out there for setting that stuff up.

I don't have instructions for other editors at this time.

Bonus: text editors

While you could use Notepad to write all your code, I highly recommend installing something smarter.

Other notes and tips