Blog

Save a C++ program as hello.cpp and try to run it directly: nothing happens. The source file needs a compiler to produce an executable. An editor makes the code easier to write; the compiler and its supporting tools build it. Knowing which tool does what makes setup problems easier to pin down.

Choose a small, complete toolchain

For a first project, you need a text editor or IDE, a C++ compiler, and a terminal. A debugger becomes useful when you start investigating program behavior, but you can check the initial setup without one. Leave build systems until after you can build a single file.

• Editor or IDE: Where you write code. An IDE may include project creation, build buttons, and debugging controls; a lightweight editor may need separate compiler integration.
• Compiler: Translates C++ source code and reports syntax and type errors. GCC and Clang are common choices; Microsoft’s MSVC is another major option on Windows.
• Standard library and linker: Provide facilities such as std::cout and combine compiled pieces into an executable. They normally come with a complete C++ toolchain.
• Terminal: Lets you check which compiler is available and see the exact command used to build a program.

An editor alone may not install a compiler. Syntax highlighting can even work in an IDE whose build tools are missing. Before troubleshooting your code, check that the compiler runs in the environment where you plan to work.

Pick one setup path for your operating system

Start with a toolchain maintained for your operating system. Use its official package manager or an official toolchain installer rather than an unexplained one-click bundle. Menus and package names change, so check that your selection includes a C++ compiler, standard library, and the build tools it needs.

Windows

Two common routes are easy to confuse. Visual Studio Community, installed with the C++ desktop development workload, provides both an IDE and the MSVC toolchain. Visual Studio Code is a lighter, separate editor; you must install and configure a C++ compiler for it. Visual Studio Code by itself is not a complete C++ setup.

If you prefer GCC or Clang, use a maintained Windows-compatible toolchain and follow its instructions for choosing a terminal and adding compiler binaries to the command path. Windows Subsystem for Linux is another option, but tools installed inside its Linux environment are not automatically available in a regular Windows terminal. Stick to one route for your first project so you do not mix headers, libraries, and compilers from different installations.

macOS

Apple’s command-line developer tools include a Clang-based C++ compiler, so you do not need a full IDE. If they are missing, open Terminal, run xcode-select --install, and follow the prompt. You can use the tools with a plain editor, a lightweight code editor, or an IDE. On macOS, g++ may invoke Apple Clang rather than GNU GCC; check the version output instead of relying on the command name.

Linux

Most distributions provide compilers and build utilities through their package manager. On Debian or Ubuntu, build-essential is a common starting package; other distributions use different names. Install from your distribution’s repositories and confirm that you have a C++ compiler, not just a C compiler. The examples below use g++. If you installed Clang, use clang++ instead.

Verify the compiler before configuring an editor

Open the terminal you intend to use for development. On Linux, macOS, or a GCC-based Windows setup, run g++ --version or clang++ --version. A version message tells you the shell found the compiler executable. It does not prove that the library and linker work; the build test below checks those too.

For MSVC, open the developer command prompt installed with Visual Studio and enter cl. An ordinary Windows command prompt may not know where MSVC and its supporting files are. If the compiler works in one terminal but not your editor’s integrated terminal, compare their environments before reinstalling anything.

“Command not found” or “not recognized” usually means the compiler is missing or its executable directory is not on that terminal’s PATH. It is not a C++ syntax error. After installing a compiler or changing environment variables, close and reopen the terminal to pick up the new settings.

Create and build a first program

Make a directory for practice projects and create hello.cpp inside it. Match the filename exactly in your build command: on case-sensitive file systems, Hello.cpp and hello.cpp are different files.

#include <iostream>

int main() {
    std::cout << "Hello, C++!n";
    return 0;
}

The #include line makes input and output declarations available. Execution starts in main. The statement writes to standard output, n starts a new line, and the zero return value indicates successful completion.

From the directory containing the file, build it with GCC:

g++ -std=c++17 -Wall -Wextra -pedantic hello.cpp -o hello

For Clang, replace g++ with clang++. -std=c++17 selects a language standard broadly supported by current toolchains. The warning options flag more questionable code, though they cannot guarantee correctness. -o hello names the executable. In this single-file build, the compiler driver handles linking as well.

Run it with ./hello on Linux or macOS. With a Windows-native GCC or Clang toolchain, use .hello.exe in PowerShell or hello.exe in Command Prompt. You should see Hello, C++!. These commands assume you are still in the project directory.

In an MSVC developer command prompt, build the same file with cl /std:c++17 /W4 /EHsc hello.cpp, then run hello.exe. MSVC flags differ from GCC and Clang flags. An “unknown option” error after mixing them up is not a source-code error.

Connect an editor without hiding the build command

Once the terminal build works, open the project directory in your editor or IDE. Add C++ language support if needed and select the compiler you just tested. Autocomplete and error underlining may work before the editor can build anything, so try its build or run action too.

If your IDE creates projects, choose a simple console application rather than a graphical template. Find out where it stores source files and writes executables. In a lightweight editor, set up a build task that runs your working compiler command from the project directory. Keep that command visible: when a build fails, you need to know which compiler, filename, and language standard it used.

An editor can index headers with one compiler while its build task uses another. The result may be misleading warnings or autocomplete that disagrees with the build. Match the editor’s compiler selection, language standard, and include paths to the real build. This first program needs neither third-party libraries nor manually copied standard-library headers.

Know which stage failed

Source code passes through several stages before it becomes a running process. Check the stage named by the error before changing code or editor settings.

If this minimal example cannot find iostream, suspect an incomplete or mismatched C++ toolchain; do not download a header by hand. If you cannot find the executable, read the build output. IDEs often write it to a project-specific build directory rather than beside hello.cpp. A successful build does not mean the program has run.

Keep the starter environment manageable

Give separate exercises separate directories instead of piling unrelated .cpp files into one folder. Your build commands stay predictable, and you are less likely to compile two files that both define main. Save source files as plain text with a .cpp extension, and note the compiler command that built each early exercise.

Use a current, supported toolchain when practical. Older course material may contain obsolete headers or nonstandard commands. As you follow an example, separate C++ language features from compiler-specific options. C++17 is a clear baseline for early exercises; change the option deliberately when a project needs a newer standard.

Keep downloaded libraries and sample projects out of your initial compiler check. Run programs you build yourself in your own practice environment, and inspect unfamiliar build scripts before executing them: they may perform file operations beyond compilation. You do not need administrator privileges to write hello.cpp or run its executable in your project directory.

For one last check, change the output text in hello.cpp, rebuild with the same command, and run the executable again. If you still see the old text, check that the build succeeded and that you ran the executable from the directory you intended.