C++ Compiling with GCC


Assuming a single source file named main.cpp, the command to compile and link an non-optimized executable is as follows (Compiling without optimization is useful for initial development and debugging, although -Og is officially recommended for newer GCC versions).

g++ -o app -Wall main.cpp -O0

To produce an optimized executable for use in production, use one of the -O options (see: -O1, -O2, -O3, -Os, -Ofast):

g++ -o app -Wall -O2 main.cpp

If the -O option is omitted, -O0, which means no optimizations, is used as default (specifying -O without a number resolves to -O1).

Alternatively, use optimization flags from the O groups (or more experimental optimizations) directly. The following example builds with -O2 optimization, plus one flag from the -O3 optimization level:

g++ -o app -Wall -O2 -ftree-partial-pre main.cpp

To produce a platform-specific optimized executable (for use in production on the machine with the same architecture), use:

g++ -o app -Wall -O2 -march=native main.cpp

Either of the above will produce a binary file that can be run with .\app.exe on Windows and ./app on Linux, Mac OS, etc.

The -o flag can also be skipped. In this case, GCC will create default output executable a.exe on Windows and a.out on Unix-like systems. To compile a file without linking it, use the -c option:

g++ -o file.o -Wall -c file.cpp

This produces an object file named file.o which can later be linked with other files to produce a binary:

g++ -o app file.o otherfile.o

More about optimization options can be found at gcc.gnu.org. Of particular note are -Og (optimization with an emphasis on debugging experience -- recommended for the standard edit-compile-debug cycle) and -Ofast (all optimizations, including ones disregarding strict standards compliance).

The -Wall flag enables warnings for many common errors and should always be used. To improve code quality it is often encouraged also to use -Wextra and other warning flags which are not automatically enabled by -Wall and -Wextra.

If the code expects a specific C++ standard, specify which standard to use by including the -std= flag. Supported values correspond to the year of finalization for each version of the ISO C++ standard. As of GCC 6.1.0, valid values for the std= flag are c++98/c++03, c++11, c++14, and c++17/c++1z. Values separated by a forward slash are equivalent.

g++ -std=c++11 <file>

GCC includes some compiler-specific extensions that are disabled when they conflict with a standard specified by the -std= flag. To compile with all extensions enabled, the value gnu++XX may be used, where XX is any of the years used by the c++ values listed above.

The default standard will be used if none is specified. For versions of GCC prior to 6.1.0, the default is -std=gnu++03; in GCC 6.1.0 and greater, the default is -std=gnu++14.

Note that due to bugs in GCC, the -pthread flag must be present at compilation and linking for GCC to support the C++ standard threading functionality introduced with C++11, such as std::thread and std::wait_for. Omitting it when using threading functions may result in no warnings but invalid results on some platforms.

Linking with libraries:

Use the -l option to pass the library name:

g++ main.cpp -lpcre2-8
#pcre2-8 is the PCRE2 library for 8bit code units (UTF-8)

If the library is not in the standard library path, add the path with -L option:

g++ main.cpp -L/my/custom/path/ -lmylib

Multiple libraries can be linked together:

g++ main.cpp -lmylib1 -lmylib2 -lmylib3

If one library depends on another, put the dependent library before the independent library:

g++ main.cpp -lchild-lib -lbase-lib

Or let the linker determine the ordering itself via --start-group and --end-group (note: this has significant performance cost):

g++ main.cpp -Wl,--start-group -lbase-lib -lchild-lib -Wl,--end-group