343 lines
8.0 KiB
Plaintext
343 lines
8.0 KiB
Plaintext
// 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! 🤠⚡*
|