axd(1)

okay bestie, we're in axd(1) territory 🎀. That's section 1 of the General Commands Manual 💅, and the manual name is axd. Let's get into it ✨

✨ NAME ✨

axd is the afnix cross debugger 🦋

🌸 SYNOPSIS 🌸

axd [options] file

💖 OPTIONS 💖

• [h] — prints the help message 🆘
• [v] — prints the program version 🔢
• [i] path — adds a directory path to the resolver 📂
• [e] mode — forces the encoding mode 🔤
• [f] runini — runs the initial file 🚀
• [f] emacs — turns on emacs mode 🧚
• [f] assert — turns on assertion checking ✅
• [f] noseed — does not seed the random engine 🎲
• [f] seed — seeds the random engine 🌱

---

🔥 DESCRIPTION 🔥

okay so axd invokes the AFNIX cross debugger and it is SO good 😭. The axd client lets you debug an AFNIX program by dropping breakpoints at strategic spots in the source code 📍. During a debugging session, once a breakpoint is hit, the program gets paused and the debugger prompt pops up 🛑.

Since the debugger is built on the AFNIX interpreter, the full power of the AFNIX interpreter is available right there at the debugger prompt. literally everything you can do in the interpreter, you can do here 💅.

🦋 VERSION 🦋

The current version is the 3.8.0 release 🎉.

🌈 SEE ALSO 🌈

• axc, axd, axl,

📝 NOTES 📝

ngl this is a lot of docs, and they're giving extensive. AFNIX comes with an extensive documentation 📚. You can read it online, or check the doc directory, where it's stored as formatted xhtml documents 💜.

👑 AUTHOR 👑

axd was written by Amaury Darsch (amaury@afnix.org) 🫶. iconic, honestly.

✨ USING THE DEBUGGER ✨

okay so this chapter is the deep dive on the cross debugger, aka axc 💅 The debugger is a special app built on top of the interpreter, which means you get the whole execution environment PLUS a dedicated nameset of special debugger commands. ✨

🦋 Invocation and termination

okay so you start the axd debugger by typing axd. Once it's running, it reads your commands straight from the terminal. Since it's built on the interpreter, every command is actually a special form the interpreter runs. The iconic way to start is to pass in the primary file you want to debug, plus any arguments you need. 🧚

zsh> axd PROGRAM [arguments]

When the debugger is up, you'll see a (axd) prompt, which means the session is live 💖 To end the session, use either axd:exit or axd:quit. Both are valid, no drama.

zsh> axd PROGRAM
(axd) axd:quit
zsh>

🎀 Debugger options

You can check the available options with the h option, and the current version with the v option. This is giving the same vibe as the interpreter's options. 🌸

zsh> axd [h]
usage: axd [options] [file] [arguments]
[h]              print this help message
[v]              print version information
[i] path         add a path to the resolver
[e   mode]       force the encoding mode
[f runini]       run initial file
[f  emacs]       enable emacs mode
[f assert]       enable assertion checks
[f nopath]       do not set initial path

Here's the breakdown of each one:

• [h] — prints the help message, the iconic usage screen 📖
• [v] — prints the version info 🔥
• [i] path — adds a path to the resolver so it knows where to look 🗺️
• [e mode] — forces the encoding mode, no questions asked 🫶
• [f runini] — runs the initial file 🚀
• [f emacs] — turns on emacs mode 💜
• [f assert] — turns on assertion checks ✅
• [f nopath] — stops the initial path from being set ⭐

🌈 Running the program

When you run a program inside the debugger, you need a primary file to say where the program should start. You can hand over the file name either as an axd command argument or with the axd:load command. Whichever one shows up first in the primary file becomes the starting point of the program 👑

🧚 Loading the program

okay so the axd:load command loads the primary file and marks the first available form as the starting form for the program. It takes a file name as its first argument, and the resolver rules apply to figuring out that file name. 🔍

• If the name has the .als extension, the string is treated as the file name, period 💅
• If the name has the .axc extension or no extension at all, the string is used to search for a file that has a .als extension or that belongs to a librarian 🔎

Heads up bestie: all of this also depends on the i option, which adds a path or a librarian to the search-path. Don't skip that part or your file search gets lost 💀

🚀 Starting the program

The axd:run command starts the program at the first available form in the primary file. It keeps running until it hits a breakpoint or some other halting condition. When the program gets suspended, you get dropped back into the debugger and the prompt shows up on the command line 🛑

(axd)axd:run

axd:run is the main command you need before you can debug anything. You can also pass a file name to use as the primary file to execute 🎀

(axd)axd:run "test.als"

💖 Setting program arguments

Since the debugger is built on the interpreter, you can mess with the argument vector directly. It's bound to the interpreter under the qualified name interp:argv, and the standard vector operations work on it 🧸

(axd)interp:argv:reset
(axd)interp:argv:append "hello"

In this example, the interpreter's argument vector gets reset, and then one single argument string, "hello", gets added. If you want to see what's in the argument vector, you can use this little procedure 👀

const argc (interp:argv:length)
loop (trans i 0) (< i argc) (i:++) {
  trans arg (interp:argv:get i)
  println "argv[" i "] = " arg
}

🦋 Breakpoints operations

Breakpoints get set with the axd:break command. When your program hits one, it gets suspended and you're back at a command prompt, where the full interpreter is available. Use that to examine symbols and see what's going on 🔬

🌸 Breakpoint command

The axd:break command sets a breakpoint in a file at a given line number. If you don't specify the file, it uses the primary file. If you don't specify the line number, it uses the first available form in the current file ⭐

(axd) axd:break "demo.als" 12
Setting breakpoint 0 in file demo.als at line 12

In this example, a breakpoint goes into demo.als at line 12. The file doesn't have to be the primary file. If you name a different file, that file gets loaded, instrumented, and then the breakpoint is set 🫶

👀 Viewing breakpoints

The axd:break-info command reports info about the current breakpoint setup, so you can see what's set where 📋

(axd) axd:break "demo.als" 12
(axd) axd:break "test.als" 18
(axd) axd:break-info
Breakpoint 0 in file demo.als at line 12
Breakpoint 1 in file test.als at line 18

🏃 Resuming execution

The axd:continue command picks the program back up after a breakpoint. It keeps going until another breaking condition is reached or the program terminates 🏁

(axd) axd:run
Breakpoint 0 in file demo.als at line 12
(axd) axd:continue

In this example, the program runs and stops at breakpoint 0, then axd:continue resumes it. Easy, bestie ✨

---

✨ DEBUGGER CONTROL REFERENCE ✨

okay this appendix is the reference for the cross debugger, axd. You start it with the axd command, and every control command is bound to the axd nameset. Think of it as your cheat sheet 📚🎀

🔴 break

The axd:breakbreak command sets a breakpoint. (Yes, the original page really spells it that way, so this is the exact name, bestie 😭) With no argument, it sets a breakpoint in the current file at the current line. With a line number, it sets the breakpoint in the current file at that line. With two arguments, the first is the file name and the second is the line number 💖

📝 Syntax

axd:break axd:break "line" axd:break "file" "line"

(axd) axd:break "demo.als"  12
(axd) axd:break 25

The first example sets a breakpoint in demo.als at line 12. The second sets a breakpoint in the current file at line 25. With no argument, the command sets the breakpoint at the current line, which you can check with the axd:info command 🧚

🔵 break-info

The axd:break-info control command reports info about the current breakpoints 📋

📝 Syntax

axd:break-info

(axd) axd:break "demo.als" 12
(axd) axd:break "test.als" 18
(axd) axd:break-info
Breakpoint 0 in file demo.als at line 12
Breakpoint 1 in file test.als at line 18

In this example, two breakpoints are set: one in demo.als at line 12 and one in test.als at line 18. axd:break-info reports the current breakpoint settings 🔍

▶️ continue

The axd:continue control command resumes program execution after a breakpoint. It keeps going until another breakpoint or terminating condition is reached 🏃‍♀️

📝 Syntax

axd:continue

(axd) axd:run
Breakpoint 0 in file demo.als at line 12
(axd) axd:continue

In this example, the program runs and stops at breakpoint 0, and axd:continue resumes it 💜

🚪 exit

The axd:exit command ends a debugger session. It's basically the same vibe as axd:quit 🫶

📝 Syntax

axd:exit

(axd) axd:exit

ℹ️ info

The axd:info command reports debugger info. That includes the debugger version, the operating system, the primary input file, the primary input file source, and more 🌈

📝 Syntax

axd:info

(axd) axd:info
debugger version    : ..
os name             : linux
os type             : unix
initial file        : 0501
form file name      : 0501.als
form line number    : 17
verbose mode        : true
max line display    : 10
defined breakpoints : 0

📜 list

The axd:list command displays the form listing starting at the current session line number. You can see the current form line number with axd:info too. The number of lines shown is a debugger parameter. You can also set the first line to display as the first parameter, and you can set a file name as well 🎀

📝 Syntax

axd:list axd:list "line" axd:list "file" "line"

(axd) axd:list
(axd) axd:list 20
(axd) axd:list "file.als" 20

The first example shows the listing at the current debugger line. The second starts the listing at line 20. The third starts at line 20 of file.als 💅

📂 load

The axd:load command sets the initial or default file to use with the axd:run control command 📁

📝 Syntax

axd:load "file"

(axd) axd:load "demo.als"

In this example, demo.als is set as the primary file. Use the axd:info command to see which line the first available form was found on 🔎

⏭️ next

The axd:next command executes the next line in the source file. It doesn't take any arguments 🦋

📝 Syntax

axd:next

(axd) axd:next

🚪 quit

The axd:quit command ends a debugger session. It's similar to the axd:exit command 🌸

📝 Syntax

axd:quit

(axd) axd:quit

🏁 run

The axd:run command executes the default file in the slave interpreter. With no argument, the initial or default file gets executed. You can use the axd:load command to set the initial file. With one argument, that file name becomes the initial file 🚀

📝 Syntax

axd:run axd:run "file"

(axd) axd:run
(axd) axd:run "demo.als"

The first example runs the initial file. The second sets demo.als as the initial file and runs it 🎉

---

That's the whole page, bestie 🫶 This manual comes from the AFNIX Client, for AFNIX, filed under axd(1). Go debug something iconic 💖🦋