Español

Penguin cpp manual

A simple C and C++ IDE for learning, for Linux and macOS (Apple Silicon). This manual is for version 0.2.2.

1. Install

See the download page. In short:

• Linux (Debian, Ubuntu, Linux Mint and derivatives): with the APT repository, sudo apt install penguin-cpp. It also installs gcc, g++, make, gdb and the formatters.
• macOS (Macs with Apple Silicon): in Terminal, curl -fsSL https://juanfrang.github.io/Penguin-cpp/install-macos.sh | bash. Compiling needs Apple's Command Line Tools; when they are missing, Penguin cpp offers to install them.

The first time, Penguin cpp looks for the system's compilers (gcc on Linux, clang on macOS) and makes three compiler sets: Release (to use), Debug (to debug) and Profiling (to profile). Pick one in the toolbar's list.

2. Your first program

1. Press New Document on the welcome screen, or File > New > Source File (Ctrl+N; on a Mac ⌘N).
2. Type:

   #include <iostream>
   using namespace std;
   
   int main() {
       string name;
       cout << "What is your name? ";
       cin >> name;
       cout << "Hello, " << name << endl;
       return 0;
   }

3. Save it as hello.cpp (Ctrl+S; on a Mac ⌘S).
4. Press F11 (Execute > Compile & Run). A terminal opens with your program; when it ends it shows how long it took and its exit code, and waits for Enter.

There is no need for system("pause") at the end: Penguin cpp already waits. Nor for system("cls") or #include <windows.h>, which exist only on Windows (see Common problems).

3. The window

• Welcome screen: new or open documents, the recent files, and the theme, font and language.
• Left panel: Project (the project's files), Classes (the functions, classes and variables of the code; a click goes to their definition) and Debug (the watched variables).
• Bottom panel: Compiler (errors and warnings; a double click goes to the line), Compile Log, Debug and Find Results.
• Toolbar: the compile and run buttons, and the list of compiler sets.

4. The editor

• Code completion: shows up after ., -> or ::, or with Ctrl+Space (on a Mac ⌥+Space). It lists the functions, variables and members of your code and of the libraries you include.
• Parameter hints: typing ( after a function shows its parameters.
• Folding: blocks in braces fold with the triangle in the margin.
• Find and replace: Ctrl+F and Ctrl+R (on a Mac ⌘F, ⌘R); F3 finds again.
• Comments: Ctrl+/ (on a Mac ⌘/) comments or uncomments the selected lines.
• Formatting: Formatting > Format Current File tidies the indentation and braces with astyle; pick the style in Formatting > Formatting Options.
• Zoom: Ctrl + mouse wheel, or Ctrl++ and Ctrl+-. On a Mac, ⌘ + wheel or a pinch on the trackpad.
• Export and print: File > Export saves the code with its colors as HTML, RTF or TeX; File > Print prints it or saves it as PDF.

5. Projects

A single file is enough for one-file exercises. Programs with several files use a project (.dev):

1. File > New > Project..., pick a template (a console application, for example), the language (C or C++) and a name.
2. Add files with the Project menu or with a right click in the Project panel.
3. Project > Options (Ctrl+H; on a Mac ⌃H): the executable's name, compiler and linker options, header and library folders, and the program's arguments.

Penguin cpp writes a Makefile for each project and builds it with make. Dev-C++ projects from Windows open too; if they use Windows libraries or headers, those have to change.

6. Compile and run

On a Mac, the F keys are pressed with fn (fn+F9…), unless System Settings > Keyboard uses them as standard function keys.

Errors show in the Compiler tab of the bottom panel; a double click goes to the line, marked in red. Programs run in a terminal: on Linux, the desktop's (chosen in Tools > Environment Options); on a Mac, Terminal. The program's arguments go in Execute > Parameters.

7. Debug

The debugger stops the program where you say, to see what it does line by line. It uses gdb on Linux and lldb on macOS; both work the same way.

1. Pick the Debug compiler set (it adds what the debugger needs) and rebuild (F12).
2. Set a breakpoint: click the margin, next to the line number, or press F4.
3. Start with Execute > Debug (F5). The program stops at the breakpoint; the current line is highlighted.
4. Go on:

   Action	Key
   Next line (without entering functions)	F7
   Into the function	F8
   Continue to the next breakpoint	Continue button
   Run to the cursor	Run to Cursor button
   Out of the function	Skip function button
   Stop	F6

5. Look at the variables:
   • Watches: Add watch (or a right click on a variable). They show in the left panel, Debug tab, and update at each step; structures and arrays unfold.
   • Hovering a variable in the code shows its value.
   • Evaluate: in the Debug tab of the bottom panel, type an expression (p.x + 1, marks[2]) and press Enter.

The program's input and output (cin, cout) go to its own terminal. In Send command (Debug tab of the bottom panel) you can type the debugger's commands (bt shows the stack, for example); the answer shows below. The View CPU window button of the debug panel shows the machine code and the registers.

8. Profile

Execute > Profile Analysis shows where your program spends its time. Penguin cpp offers to turn profiling on, rebuilds, runs the program and opens the results.

• Linux (gprof): the time and calls of each function, and the graph of who calls whom.
• macOS (LLVM): how many times each function was called, most called first (macOS measures no times and has no call graph).

9. Options

• Tools > Compiler Options: the compiler sets (Release, Debug, Profiling), their options (C++ standard, optimization, warnings) and their programs.
• Tools > Environment Options: language, theme, terminal (Linux) and folders.
• Tools > Editor Options: the font, the code's colors (light and dark schemes), tabs and code completion.
• Tools > Configure Shortcuts: change any shortcut.

Settings are kept in ~/.config/penguin-cpp (Linux) or ~/Library/Application Support/penguin-cpp (macOS). To start over, close Penguin cpp and delete that folder.

10. Keyboard shortcuts

On a Mac, ⌘ (Command) takes the place of Ctrl, except in the shortcuts macOS keeps for itself (⌘Space, ⌘Tab, ⌘H, ⌘M, ⌘Q), which stay with ⌃ (Control).

On a Mac, the editor also knows the Mac's keys: ⌘ + arrows (start and end of the line or the file), ⌥ + arrows (word by word) and ⌥/⌘ + delete.

11. Common problems

"windows.h: No such file or directory" (or conio.h)

windows.h and conio.h belong to Windows and do not exist on Linux or macOS. They are mostly used for console things that have portable equivalents:

Code completion does not show (Mac)

Use ⌥Space. macOS takes ⌃Space to switch keyboards when there is more than one; it can be freed in System Settings > Keyboard > Keyboard Shortcuts > Input Sources.

The F keys do nothing (Mac)

Press them with fn, or turn on Use F1, F2, etc. keys as standard function keys in System Settings > Keyboard.

macOS says the app "is damaged" or cannot be verified

Install it with the one-line installer of the download page, or in Terminal: xattr -cr "/Applications/Penguin cpp.app".

The compiler was not found

On Linux: sudo apt install g++ gdb make. On a Mac: xcode-select --install. Then close and open Penguin cpp.

No terminal opens when running (Linux)

Install one (for example sudo apt install xterm) or pick yours in Tools > Environment Options.

12. Report a problem

When Penguin cpp has an error, it writes it to penguin-cpp-errores.txt on your Desktop and offers to open it when you close. Write to jfgonzalez@unimagdalena.edu.co with the version, your system, what you did, what you expected and what happened, and attach that file, a screenshot and the code it happens with. The download page has an example.

Penguin cpp is free software (GPL v2 or later), based on Embarcadero Dev-C++. Code: github.com/JuanFranG/Penguin-cpp.