![[Ficl on NDS]](ficlNDS.jpg)
Click image to enlarge
What follows are instructions for (i) installing and running the FINC web server on a Nintendo DS and (ii) installing and running other Forth code on the DS.
|
|
|
Ficl in DeSmuME - Click image to enlarge |
The Ficl executable (see Running other Forth Code) and FINC executable were built using the devkitPro tool chain (devkitARM installation instructions). [But see Building Ficl for the DS below for important information about devkitPro versions.] Ficl and FINC run as standard I/O (i.e., dumb terminal) applications on the Nintendo DS. Output is written to the top screen; input, when requested by the program, is read from a pop-up keyboard on the bottom screen.
On start-up, both executables look for a configuration file,
"/etc/program.conf", that defines (i) any
environment variables needed by the program and (ii) a UNIX-like
command line with arguments for the program. If there is no configuration
file or if there is no command line in the file, the program prompts you
for the command-line arguments. Hit "Rtrn" on the keyboard and you'll be
met by the standard Forth "ok> " prompt. If you can manage
entering more than a few keystrokes without frustration, more power to you!
Caveats: I've found some shortcomings in Ficl - PICK and
FILE-SIZE are implemented incorrectly and the String word set (except for
COMPARE) is missing. See the beginning of
"utility.fr" for work-arounds.
(Of course, there may be other bugs I haven't encountered yet.)
finc.nds - the Ficl/FINC executable.
httpd.fr - the Forth code for
the web server.
utility.fr - Forth utility
words.
etc" directory in the root directory ("/") of your
DS. Then copy these files to "/etc/":
mime.types - a MIME types file.
This is a large MIME types file, so the Ficl dictionary size has to
be increased beyond its default size, which is done via an environment
variable in the following file, the FINC configuration file:
finc.conf - the start-up
configuration file for FINC. This file defines (i) a couple
of environment variables needed by the web server and (ii) the
FINC command line, which tells FINC to load the "httpd.fr"
file.
/public_html/":
Simply select "finc.nds" and run it. The program will pick up
its environment variables and command line from "/etc/finc.conf".
Per the configuration file, FINC will load and execute the web server code
from "httpd.fr" (which itself loads "utility.fr").
The web server listens at default port 80 for connection requests from browsers. Assuming you know the IP address of the DS, enter a URL like the following in your browser to connect to your web site on the DS:
http://IP-address/
The URL above will read "/public_html/index.html" from the DS.
If that is not the main entry point of your web site, just modify the URL
accordingly.
The Ficl/FINC executable, "finc.nds", is not limited to running
only the web server. To run your own Forth code, just copy the Forth file(s)
into the DS root directory and modify the command line in
"/etc/finc.conf" to load your main file instead of
"httpd.fr".
If you're not interested in the networking extensions provided by FINC,
you can run the vanilla Ficl executable,
"ficl.nds". In this case, Ficl looks
for configuration file "/etc/ficl.conf" containing a command
line, "ficl argument(s)".
FINC (but not vanilla Ficl) allows you to remotely connect to the program in order to interact with the Forth interpreter. This is accomplished with a command-line option:
finc -listen port [... other options ...]
FINC will wait for and accept the first client connection request at the specified network port before starting the interpreter and processing the other command-line options. The client network connection is used in place of Ficl's default standard input, standard output, and standard error streams.
telnet is the obvious client for connecting to FINC. If FINC is listening on port 12345 and the DS's IP address is 192.168.1.7, then running telnet will produce the following initial output:
% telnet 192.168.1.7 12345
Trying 192.168.1.7...
Connected to 192.168.1.7.
Escape character is '^]'.
loading CORE EXT words
loading SEARCH & SEARCH-EXT words
loading Johns-Hopkins locals
loading MARKER
loading ficl O-O extensions
loading ficl utility classes
loading ficl string class
Ficl version 4.1.0
Finc Apr 2 2011
ok> cursor
You can now enter Forth code, examine the stack, etc.
Debug and error output from the networking library on which FINC is based will continue to be written to standard output and standard error on the top screen of the DS.
Note: I originally built FINC for the DS in 2009:
devkitPro R24 and ficl4.0.31. In 2011, I downloaded new versions
of both pieces of software: devkitPro R32 and ficl-4.1.0.
Unfortunately, in the web server, FINC would report an error ("data stack
underflow") when returning from the INCLUDED of
utility.fr from within httpd.fr.
(The web server runs fine under Linux.) Trying the different combinations of
old and new software revealed that I needed to build FINC with the
old devkitPro (and either version of Ficl) in order
to get a working web server (i.e., one that didn't suffer from the stack
underflow). Consequently, the ficl.nds and
finc.nds executables above are built using
devkitPro R24 and ficl-4.1.0. (StdIONDS.c
below has devkitPro-release dependencies, so it and
Makefile.nds make use of C Preprocessor symbol
DEVKITPRO_R24.)
Building the basic Ficl for the Nintendo DS is a fairly simple job:
Makefile.nds and
StdIONDS.c into the target directory.
make -f Makefile.nds".
The Make command builds (i) the "libficl.a" library
needed by FINC and (ii) the "ficl.nds" executable
needed to run on your Nintendo DS. Done!