@node Tutorials
@chapter Tutorials

@cindex tutorials
@cindex walkthrough
@cindex hello world

This chapter provides step-by-step walkthroughs of common tasks.

All workflows in this chapter have been verified with xwpe 1.6.2
on 2026-05-29 with gcc 15.2, g++ 15.2, gfortran 15.2, fpc 3.2.2,
javac 25, gdb 17.2, and jdb 25.  Example files are in
@file{docs/examples/}.

@section Tutorial 1: Hello World in C

@subsection Goal
Create, compile, and run a simple C program entirely within xwpe.

@subsection Steps

@enumerate
@item
Start xwpe in programming mode:
@example
wpe
@end example

@item
Create a new file: @kbd{Alt-F N}.  A new buffer named ``Noname'' opens.

@item
Type the program:
@example
#include <stdio.h>

int main() @{
    printf("Hello, world!\n");
    return 0;
@}
@end example

@item
Save the file: @kbd{Alt-F A} (Save As), type @code{hello.c}, press
@key{Return}.

@item
Compile: press @key{F9} (Make).  xwpe invokes @code{gcc -c -o hello.o
hello.c} and then links the executable.  If there are errors, they
appear in the Message Window; press @kbd{Alt-R N} to jump to each
error.

@item
Run: press @kbd{Ctrl-F9} (Run).  The program executes and
``Hello, world!'' appears in the output.

@item
Quit: press @kbd{Ctrl-Q}.
@end enumerate

@section Tutorial 2: Multi-file project

@subsection Goal
Create a project with two source files and a shared header.

@subsection Steps

@enumerate
@item
Create three files:

@file{main.c}:
@example
#include <stdio.h>
#include "utils.h"

int main() @{
    printf("Sum: %d\n", add(3, 4));
    return 0;
@}
@end example

@file{utils.h}:
@example
int add(int a, int b);
@end example

@file{utils.c}:
@example
#include "utils.h"

int add(int a, int b) @{
    return a + b;
@}
@end example

@item
Open a project: @kbd{Alt-P P}, type @code{myproject}, press
@key{Return}.

@item
Configure the project in the options dialog:
@itemize @bullet
@item Compiler: @code{/usr/bin/gcc}
@item Compiler Options: @code{-Wall -g}
@item Executable Name: @code{myprogram}
@end itemize

@item
Add files to the project: @kbd{Alt-P A}, add @code{main.c} and
@code{utils.c}.

@item
Build: press @key{F9}.  xwpe compiles both files and links them
into @code{myprogram}.

@item
Run: press @kbd{Ctrl-F9}.  Output: @code{Sum: 7}.
@end enumerate

@section Tutorial 3: Debugging a segfault

@subsection Goal
Use the integrated debugger to find and fix a null pointer dereference.

@subsection Steps

@enumerate
@item
Create @file{buggy.c}:
@example
#include <stdio.h>

int factorial(int n) @{
    if (n <= 1) return 1;
    return n * factorial(n - 1);
@}

int main() @{
    int x = 5;
    int result = factorial(x);
    printf("factorial(%d) = %d\n", x, result);

    int *ptr = NULL;
    *ptr = 42;  /* deliberate crash */

    return 0;
@}
@end example

@item
Compile with debug symbols: the default options include @code{-g}.
Press @key{F9} to compile and link.

@item
Set a breakpoint at @code{int x = 5;}: move the cursor there and
press @kbd{Ctrl-G B} (or @kbd{Ctrl-F8}).

@item
Start the debugger: press @kbd{Ctrl-G R} (or @kbd{Ctrl-F10}).
The program compiles, links, launches gdb, and stops at the breakpoint.

@item
Add a watch: press @kbd{Ctrl-F7}, type @code{x}, press @key{Return}.
The Watch Window shows the value of @code{x}.

@item
Step through: press @key{F8} repeatedly.  Watch @code{x} and
@code{result} change as the program executes.

@item
When the program reaches @code{*ptr = 42;}, it will crash with
SIGSEGV.  gdb catches the signal and xwpe shows the offending line.

@item
View the stack: press @kbd{Ctrl-F6} to see that the crash occurred
in @code{main()} at the null pointer dereference.

@item
Fix the bug: remove or comment out the @code{*ptr = 42;} line.
Recompile with @key{F9} and run with @kbd{Ctrl-F9}.

@item
Quit the debugger: press @kbd{Ctrl-G Q} (or @kbd{Ctrl-F2}).
@end enumerate

@section Tutorial 4: Java compile and debug

@subsection Goal
Compile a Java program, navigate errors, and debug with jdb.

@subsection Steps

@enumerate
@item
Open the example file:
@example
wpe docs/examples/debug_test.java
@end example

@item
Press @key{F9} to compile.  xwpe auto-detects @command{javac} for
@file{.java} files.

@item
Set a breakpoint: move cursor to line 7 (@code{int x = 5;}) and
press @kbd{Ctrl-G B}.

@item
Press @kbd{Ctrl-G R} to start the debugger.  xwpe auto-selects
@command{jdb} for Java files.  The JVM takes 2--3 seconds to start.

@item
Press @key{F8} to step through the code.  The active line is
highlighted.  Step past the @code{println} line.

@item
Press @kbd{Ctrl-G P} to see program output:
@example
--- Program output ---
factorial(5) = 120
--- Press any key to return to editor ---
@end example

@item
When the program finishes, xwpe exits the debugger cleanly and
returns to the editor.
@end enumerate

@subsection Notes

jdb is the only debugger backend that doesn't use gdb.  The
@code{-c} flag that caused problems with non-GNU compilers
(@pxref{Compiling}) was fixed in v1.6.2 --- a bug first reported
by Miroslav Jani@v{s} in 1998 for @LaTeX{}.

@section Tutorial 5: Navigating multiple errors

@subsection Goal
Use @kbd{Alt-T} and @kbd{Alt-V} to jump between compiler errors.

@subsection Steps

@enumerate
@item
Open an example file with deliberate errors:
@example
wpe docs/examples/compile_error_test.c
@end example

@item
Press @key{F9} to compile.  Two errors appear in the Messages window.

@item
Press @kbd{Alt-T} (Next Error).  The cursor jumps to the first error
(line 4, column 13).

@item
Press @kbd{Alt-T} again.  The cursor jumps to the second error
(line 8).

@item
Press @kbd{Alt-V} (Previous Error).  The cursor returns to the
first error.
@end enumerate

@subsection Notes

Error navigation works with all tested compilers: gcc, g++,
gfortran (blank lines between errors are handled), fpc
(@code{file(line,column)} format), and javac (@code{file:line:}
format, cursor goes to start of line since javac doesn't report
columns).  See @file{docs/examples/} for error test files in all
five languages.
