// Moved from docs/src/getting-started/QUICKSTART.adoc to docs/working/scratch/src/getting-started/QUICKSTART.adoc on 2026-06-16 (docs reorg Phase 2)
== StarForth - Quick Start Guide
:toc: left
:toc-title: Contents
:toclevels: 3
xref:../README.adoc[← Back to Documentation Index]



=== 🤠 The Fastest Forth in the West!

==== One-Line Quick Start

[source,bash]
----
# Build the fastest version for your platform
make fastest
----

=== 🚀 Common Commands

[width="100%",cols="26%,37%,37%",options="header",]
|===
|Command |What It Does |When To Use
|`+make fastest+` |Maximum speed build |Production, benchmarking
|`+make fast+` |Fast without LTO |Development, debugging
|`+make debug+` |Debug build (-g -O0) |Debugging with GDB
|`+make benchmark+` |Run full benchmark suite |Performance testing
|`+make help+` |Show all options |When you forget 😅
|===

=== 🎯 Platform-Specific Builds

==== On x86_64 Linux

[source,bash]
----
make fastest              # Auto-detects x86_64, builds with ASM optimizations
./build/starforth         # Run it!
----

==== On Raspberry Pi 4

[source,bash]
----
make fastest              # Auto-detects ARM64, builds optimized for Cortex-A72
./build/starforth
----

==== Cross-Compile for Raspberry Pi 4

[source,bash]
----
# On your x86_64 development machine (requires gcc-aarch64-linux-gnu):
make rpi4-cross          # Builds 987 KB ARM64 binary with inline ASM

# Copy to Raspberry Pi:
scp build/starforth pi@raspberrypi.local:~/

# On Raspberry Pi:
./starforth              # Statically linked, ready to run!
----

*Note:* ARM64 cross-compilation has been tested and verified. The binary
includes inline assembly optimizations for ARM64/AArch64.

=== ⚡ Performance Modes

==== Speed Rankings (Fastest to Slowest)

[arabic]
. *`+make pgo+`* - Profile-Guided Optimization ⭐ ULTIMATE
* Two-stage build with profiling
* 5-15% faster than `+fastest+`
* Takes 2-3x longer to build
. *`+make fastest+`* - Maximum Performance ⭐ RECOMMENDED
* Assembly optimizations
* Direct threading
* LTO enabled
* Best balance of speed and build time
. *`+make fast+`* - Fast Development
* Assembly optimizations
* Direct threading
* No LTO (easier debugging)
. *`+make turbo+`* - Assembly Only
* Assembly optimizations
* No direct threading
* Good middle ground
. *`+make all+`* - Standard Build
* Default optimizations (-O2)
* No assembly optimizations
. *`+make debug+`* - Debug Build
* No optimizations (-O0)
* Full debug symbols (-g)

=== 🔧 INIT System

StarForth automatically loads `+./conf/init.4th+` at startup, which
contains foundational Forth definitions. This is completely automatic -
just run starforth and it’s ready to go!

[source,bash]
----
./build/starforth
# INIT runs automatically...
ok> F              # Words from init.4th are immediately available
----

*What INIT does:* - Loads blocks from `+./conf/init.4th+` - Executes
them (defines words) - Protects them from FORGET (dictionary fence) -
Zeros blocks for your use

📖 *link:docs/INIT_SYSTEM.md[Full INIT Documentation →]*

=== 🧪 Testing & Benchmarking

[source,bash]
----
# Quick benchmark (1 million operations)
make bench

# Full benchmark suite
make benchmark

# Run test suite
make test
----

==== Expected Performance (1M stack operations)

[cols=",,",options="header",]
|===
|Build Type |x86_64 |ARM64 (RPi4)
|Debug |~800ms |~1200ms
|Standard |~250ms |~380ms
|Fastest |~60ms |~95ms
|PGO |~50ms |~80ms
|===

=== 📝 Generate Assembly

[source,bash]
----
# Generate .s files for inspection
make asm

# View assembly
less build/stack_management.s
----

=== 🧹 Cleanup

[source,bash]
----
# Clean everything
make clean

# Clean only object files (keep executables)
make clean-obj
----

=== 🔧 Advanced Usage

==== Custom Compiler Flags

[source,bash]
----
make fastest CFLAGS="$(make -s print-cflags) -DCUSTOM_FLAG"
----

==== Static Binary

[source,bash]
----
make fastest LDFLAGS="-static -s"
----

==== Different Compiler

[source,bash]
----
make fastest CC=clang
----

==== Cross-Compilation

[source,bash]
----
make fastest CC=aarch64-linux-gnu-gcc \
             CFLAGS="..." \
             LDFLAGS="-static"
----

=== 🎓 Understanding the Build Flags

==== What’s Enabled in `+make fastest+`?

[cols=",",options="header",]
|===
|Flag |What It Does
|`+-O3+` |Maximum optimization
|`+-march=native+` (x86_64) |Use all CPU features
|`+-march=armv8-a+crc+simd+` (ARM64) |ARMv8 + NEON
|`+-DUSE_ASM_OPT=1+` |Enable assembly optimizations
|`+-DUSE_DIRECT_THREADING=1+` |Direct-threaded interpreter
|`+-flto+` |Link-Time Optimization
|`+-funroll-loops+` |Unroll loops
|`+-finline-functions+` |Aggressive inlining
|`+-fomit-frame-pointer+` |Use register for extra speed
|===

=== 🐛 Debugging

==== Debug Build

[source,bash]
----
make debug
gdb build/starforth
----

==== Debug Optimized Build

[source,bash]
----
make fast CFLAGS="$(make -s print-cflags) -g"
gdb build/starforth
----

==== Verify Optimizations Are Working

[source,bash]
----
# Check for assembly symbols
nm build/starforth | grep -i "vm_push_asm"

# Check architecture
file build/starforth

# Check for LTO
readelf -s build/starforth | grep -i lto
----

=== 📊 Comparing Builds

[source,bash]
----
# Build baseline
make clean && make all
cp build/starforth build/starforth_baseline

# Build optimized
make clean && make fastest
cp build/starforth build/starforth_fastest

# Compare sizes
ls -lh build/starforth_*

# Compare performance
time ./build/starforth_baseline -c ": TEST 1000000 0 DO 1 2 + DROP LOOP ; TEST BYE"
time ./build/starforth_fastest -c ": TEST 1000000 0 DO 1 2 + DROP LOOP ; TEST BYE"
----

=== 🏆 Performance Tips

[arabic]
. *Use `+make fastest+`* for production
. *Add heatsink* on Raspberry Pi 4 for sustained performance
. *Set CPU governor* to `+performance+`:
+
[source,bash]
----
echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
----
. *Use `+make pgo+`* for ultimate performance (takes longer to build)
. *Profile your workload* and customize optimization flags

=== 📚 More Information

* *Full Documentation*: See `+docs/+` directory
* *Assembly Optimizations*: `+docs/ASM_OPTIMIZATIONS.md+`
* *ARM64 Guide*: `+docs/ARM64_OPTIMIZATIONS.md+`
* *Raspberry Pi*: `+docs/RASPBERRY_PI_BUILD.md+`
* *L4Re Integration*: `+docs/L4RE_INTEGRATION.md+`

=== 🆘 Troubleshooting

==== "`Illegal instruction`" Error

[source,bash]
----
# Your CPU doesn't support all optimizations
# Use more conservative flags:
make fastest CFLAGS="$(BASE_CFLAGS) -O3 -march=x86-64 -DUSE_ASM_OPT=1"
----

==== Build Errors

[source,bash]
----
# Try standard build first:
make clean && make all

# If that works, gradually add optimizations:
make clean && make fast
make clean && make fastest
----

==== Slow Performance

[source,bash]
----
# Verify optimizations are enabled:
./build/starforth --version  # (if implemented)

# Or check binary:
file build/starforth
nm build/starforth | grep vm_push_asm
----

=== 🎯 Quick Reference Card

....
╔══════════════════════════════════════════════════╗
║  🤠 FASTEST FORTH IN THE WEST - QUICK REFERENCE  ║
╠══════════════════════════════════════════════════╣
║                                                  ║
║  BUILD:           make fastest                   ║
║  BENCHMARK:       make benchmark                 ║
║  DEBUG:           make debug                     ║
║  CLEAN:           make clean                     ║
║  HELP:            make help                      ║
║                                                  ║
║  RASPBERRY PI 4:  make rpi4-cross                ║
║  ULTIMATE SPEED:  make pgo                       ║
║                                                  ║
╚══════════════════════════════════════════════════╝
....

'''''

*Now go forth and be the fastest! 🤠⚡*
