Skip to main content

​
Overview

Building Timo from source gives you access to the latest development version and allows you to customize the application for your needs. This guide covers everything from prerequisites to troubleshooting.

​
Prerequisites

Before building Timo, ensure you have the required tools installed.

​
Rust Toolchain

Timo requires Rust 2021 edition or later.
1

Install Rust

Install Rust using rustup (recommended method):
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Follow the on-screen instructions to complete the installation.
2

Verify Installation

Confirm Rust and Cargo are installed:
rustc --version
cargo --version
You should see version numbers for both commands.
3

Update Rust (Optional)

If you already have Rust installed, update to the latest version:
rustup update

​
System Requirements

Operating System

  • Linux (any distribution)
  • macOS 10.13 or later
  • Windows 10 or later

Development Tools

  • Git for cloning the repository
  • C compiler (for SQLite bundled build)
  • Internet connection for dependencies

​
Building Timo

1

Clone the Repository

Clone the Timo repository from GitHub:
git clone https://github.com/abhishek6262/timo.git
cd timo
This downloads the complete source code including all dependencies defined in Cargo.toml.
2

Build the Project

Build Timo in release mode for optimal performance:
cargo build --release
This will:
  • Download and compile all dependencies (clap, rusqlite, refinery, colored, dirs, dotenv)
  • Build a bundled SQLite library
  • Compile Timo with optimizations
  • Create the binary in target/release/timo
The first build will take longer as it downloads and compiles dependencies. Subsequent builds will be faster.
3

Test the Build

Verify the build was successful by running Timo:
./target/release/timo --version
./target/release/timo help
You should see the version number and help information.

​
Installing Timo

After building, install Timo globally to use it from anywhere.
Install directly using Cargo (recommended):
cargo install --path .
This installs the binary to ~/.cargo/bin/timo, which should be in your PATH.Verify the installation:
timo --version

​
Development Build

For development and testing, you can build without optimizations: 
# Build in debug mode (faster compilation, slower runtime)
cargo build

# Run directly without building a binary
cargo run -- add "Test thought"
cargo run -- list
Debug builds are faster to compile but slower to execute. Use them during development.

​
Running Tests

The current codebase does not include automated tests. This section describes how to manually test the application.

​
Manual Testing

Test all commands to ensure functionality: 
# Set a custom database for testing
export DB_NAME=".timo-test.db"

# Test adding thoughts
cargo run -- add "Buy groceries" -l errands
cargo run -- add "Team meeting at 3pm" -l work
cargo run -- add "Read Rust book"

# Test listing
cargo run -- list
cargo run -- list -l work
cargo run -- list -s  # Show labels

# Test searching
cargo run -- search meeting
cargo run -- search groceries -l errands

# Test removal
cargo run -- remove 1
cargo run -- remove 2 3

# Test clearing
cargo run -- clear --confirmed

​
Database Testing

The SQLite database is stored in your local data directory. To test with a clean database: 
rm ~/.local/share/.timo.db
cargo run -- add "First thought"

​
Project Structure

Understanding the source structure helps when modifying or debugging: 
timo/
├── Cargo.toml                 # Project metadata and dependencies
├── Cargo.lock                 # Dependency lock file
├── LICENSE.txt                # MIT license
├── readme.md                  # Project README
└── src/
    ├── main.rs                # Application entry point
    ├── app.rs                 # App initialization
    ├── cli.rs                 # CLI interface
    ├── commands.rs            # Command definitions
    ├── executor.rs            # Command execution
    ├── task.rs                # Task model
    ├── task_service.rs        # Business logic
    ├── task_repository.rs     # Data access layer
    ├── task_printer.rs        # Output formatting
    ├── storage.rs             # Storage trait
    ├── sqlite/
    │   ├── mod.rs
    │   ├── sqlite_storage.rs  # SQLite implementation
    │   └── migration.rs       # Migration runner
    └── sql_migrations/
        ├── V1__create_tasks_table.sql
        └── V2__add_label_column_in_tasks_table.sql
See the Architecture documentation for detailed component descriptions.

​
Troubleshooting

Problem: Cargo fails to compile dependenciesSolutions:
  • Update Rust: rustup update
  • Clear the build cache: cargo clean
  • Delete Cargo.lock and rebuild: rm Cargo.lock && cargo build --release
  • Ensure you have a C compiler installed for SQLite bundled build
    • Linux: sudo apt-get install build-essential
    • macOS: xcode-select --install
    • Windows: Install Visual Studio Build Tools
Problem: Error building rusqlite with bundled featureSolutions:
  • Install C compiler and development tools (see above)
  • On Linux, install additional dependencies: 
    sudo apt-get install libsqlite3-dev
  • Check that you have sufficient disk space
Problem: timo: command not found after installationSolutions:
  • Ensure ~/.cargo/bin is in your PATH: 
    echo $PATH | grep cargo
  • Add to PATH if missing (add to ~/.bashrc or ~/.zshrc): 
    export PATH="$HOME/.cargo/bin:$PATH"
  • Restart your terminal or run: 
    source ~/.bashrc  # or ~/.zshrc
Problem: Permission denied when running the binarySolutions:
  • Make the binary executable: 
    chmod +x target/release/timo
  • If using manual install, use sudo for system directories
Problem: Cannot create or access database fileSolutions:
  • Check permissions on the local data directory:
    • Linux: ~/.local/share/
    • macOS: ~/Library/Application Support/
  • Ensure the directory exists and is writable: 
    mkdir -p ~/.local/share  # Linux
chmod 755 ~/.local/share
Problem: Database migration fails on startupSolutions:
  • Delete the database and let Timo recreate it: 
    rm ~/.local/share/.timo.db
  • Check that src/sql_migrations/ directory exists with migration files
  • Ensure migrations are embedded at compile time

​
Customizing the Build

​
Custom Database Location

Set the DB_NAME environment variable before running: 
# Development database
export DB_NAME=".timo-dev.db"
cargo run -- list

# Or inline for a single command
DB_NAME=".timo-test.db" cargo run -- add "Test"

​
Build Profiles

Customize build settings in Cargo.toml: 
[profile.release]
opt-level = 3        # Maximum optimization
lto = true          # Link-time optimization
codegen-units = 1   # Better optimization, slower compile
strip = true        # Remove debug symbols

​
Cross-Compilation

Build for different platforms: 
# Install cross-compilation target
rustup target add x86_64-unknown-linux-musl

# Build for the target
cargo build --release --target x86_64-unknown-linux-musl

​
Development Workflow

​
Quick Iteration

For rapid development: 
# Use cargo-watch for automatic rebuilds
cargo install cargo-watch
cargo watch -x 'run -- list'

# Format code before committing
cargo fmt

# Check for common issues
cargo clippy

​
Debugging

Run with debug output: 
# Use the debug build
cargo build

# Run with backtrace for panics
RUST_BACKTRACE=1 ./target/debug/timo list

# Full backtrace for detailed errors
RUST_BACKTRACE=full ./target/debug/timo list

​
Next Steps

Architecture

Learn about the codebase structure and design patterns

Contributing

Contribute improvements and new features

Commands

Explore all available commands

Labels

Learn how to organize thoughts with labels

​
Additional Resources

Rust Book

Learn Rust programming language

Cargo Documentation

Master Rust’s package manager

Clap Documentation

Understand the CLI framework

Rusqlite Documentation

Work with SQLite in Rust

Build docs developers (and LLMs) love

Get started for freeTalk to us