Home

GEONius.com
6-Apr-2011
E-mail

FINC Web Server on a Nintendo DS

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 on NDS]
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.)

Installation

  1. Copy these files to the root directory ("/") of your DS:


  2. Create an "etc" directory in the root directory ("/") of your DS. Then copy these files to "/etc/":


  3. Create a "public_html" directory in the root directory ("/") of your DS. Then copy your web site (HTML tree) to "/public_html/":

Running the Web Server

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.

Running other Forth Code

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)".

Remote Access to the Forth Interpreter

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.

Building Ficl for 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:

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!


Alex Measday  /  E-mail