Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

How to Use This Tutorial

This sections explains how to work through this guide effectively. While you can read individual sections independently, this tutorial is designed to be followed in order.

The tutorial is structured progressively:

  1. Environment Setup
  2. Project Creation
  3. User Interface Design
  4. Application Logic
  5. API Integration
  6. Threading and Concurrency
  7. Local Data Storage
  8. Debugging
  9. Flatpak Packaging

Each section builds on knowledge from the previous one.

For best results, follow the chapters sequentially.

Estimated Time Commitment

This tutorial is designed to be completed in approximately:

  • 8–10 hours total
    or
  • 2–3 focused sessions

Time may vary depending on:

  • Your familiarity with Rust
  • Your Linux experience
  • Whether you explore additional experiments

Do not rush. The goal is understanding, not speed.

Development Setup Recommendation

It is strongly recommended to use:

  • A clean Linux installation
    or
  • A fresh virtual machine (VM)

Why?

Because this tutorial simulates the onboarding experience of a new developer starting from scratch.

Using a clean system ensures:

  • You install all required dependencies yourself
  • You see common setup issues
  • You understand how the full environment works

If you already have Rust or GTK installed, that is fine but be aware that some steps may behave differently.

How to Follow Along

For each chapter:

  1. Read the explanation carefully.
  2. Type the commands manually (avoid copy-pasting everything).
  3. Run the application after each major step.
  4. Verify that your output matches the expected result.
  5. Only then continue to the next section.

Typing commands manually helps you understand what is happening.

Handling Errors

It is normal to encounter errors during development.

Common examples include:

  • Missing system libraries
  • Version mismatches
  • Flatpak runtime issues
  • GTK builder validation errors
  • Network-related API errors

If something fails:

  1. Read the error message carefully.
  2. Compare your output with the documentation.
  3. Check the "Debugging and Common Errors" section.
  4. Search the official documentation if necessary.

Do not panic debugging is part of the learning process.

Experimentation Is Encouraged

You are encouraged to experiment during this tutorial.

For example:

  • Change window sizes and observe layout behavior
  • Modify labels and UI elements
  • Try invalid city names
  • Remove network permission in Flatpak and observe what happens
  • Intentionally break something and fix it

Understanding how systems fail is just as important as understanding how they work.

Understanding the Structure

Each chapter typically includes:

  • Concept explanation
  • Code example
  • Step-by-step instructions
  • Expected output
  • Notes about common pitfalls

Try to understand:

  • Why each dependency is needed
  • Why background threads are required
  • Why Flatpak requires specific permissions
  • Why certain GTK widgets are chosen

The goal is comprehension, not just completion.

When You Get Stuck

If you are stuck:

  • Re-read the previous section
  • Check that all dependencies are installed
  • Verify your Cargo.toml versions
  • Rebuild using cargo clean
  • Rebuild Flatpak using --force-clean

Sometimes rebuilding from scratch solves environment-related issues.

Final Advice Before You Begin

  • Be patient.
  • Take notes.
  • Test frequently.
  • Do not skip sections.

By the end of this tutorial, you will not only have a working application you will understand how modern Linux applications are built, structured, and distributed.

Continue to the next chapter to prepare your development environment.