nqc(1)

📦
version 4.1.0 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 nqc(1) — the manual, but make it make sense 💖

okay bestie, welcome to the General Commands Manual entry for nqc, aka the little compiler that could. sit down, grab a boba, and let's get into it 🧋✨

✨ NAME ✨

nqc — a simple C-like language for Lego's RCX programmable brick 🧱👑

🦋 SYNOPSIS 🦋

nqc [ options ] [ actions ] [ - | filename ] [ actions ]

🌸 DESCRIPTION 🌸

NQC stands for Not Quite C, and it's a simple language for programming the LEGO RCX. the preprocessor and control structures of NQC are very similar to C. but — and this is the important part, bestie — NQC is not a general purpose language. there are so many restrictions that stem from limitations of the standard RCX firmware. it's giving "C's little sister who lives in a plastic brick" 💅

this man page does not attempt to describe the NQC programming language or the RCX API, only the options of the nqc command-line program. references to more complete documentation are given at the end of this man page. 👑

nqc is normally used to process a single source file given as filename. you can also read from stdin by using - instead. and if the filename ends in .rcx, it is assumed to be a RCX image file from a previous compile, and will be used as is (for downloading or listing). no cap 🫶

💅 OPTIONS 💅

  • -1 — use NQC 1.x compatibility mode. the RCX API changed significantly with version 2.0, and this flag makes the compiler grok old code. throwback era fr fr 🕰️
  • -Ttarget — generate code and use communications methods for "smart bricks" other than the RCX. currently, target can be either CM or Scout.
  • -d — download program to the RCX. when this option is given, code is sent directly over the serial port to the brick and no output file is generated by default. it's giving direct delivery 📦✨
  • -n — prevent the standard nqc.h file from being automatically included. you're on your own, main character 🎀
  • -Dsym[=value] — define macro sym as value.
  • -E[filename] — write compiler errors to filename (or to stdout, if no name specified) instead of to stderr. errors, but make it your choice of destination 😭
  • -Ipath — search path for include files. multiple directories should be separated as normal for the platform (under Linux / Unix, that'd be ""). can also be set with the NQC_INCLUDE environment variable.
  • -L[filename] — generate a human-readable bytecode listing to filename (or to stdout) instead of generating a binary file. lowkey the prettiest option ngl 🌈
  • -Ooutfile — output code to outfile. this option causes a file to be written even if -d or -L is also given. if no filename is specified, the output file will have the same basename as the input file but an extension of .rcx instead of .nqc.
  • -Sportname — use serial port portname. under Linux, /dev/ttyS0 is the default. (this will differ on other platforms.) the port can also be specified via the RCX_PORT environment variable, but the command line option takes precedence. command line stays winning 👑
  • -Usym — undefine macro sym. okay un-define it then 💀

🔥 ACTIONS 🔥

actions look similar to options, but they have some subtle differences. in general, options set up things (such as a serial port) for later use, while actions cause something to happen. actions are executed in the order that they appear on the command line. plus, actions appearing before the source file happen before compilation, while actions after the source file happen after compilation. for historical reasons, downloading the compiled file (-d) works as an option and not an action. the lore is real 🧚

  • -run — run the current program. this causes the program selected on the RCX to execute. go bestie go 🏃♀️
  • -pgm number — select program number. this changes the program slot on the RCX.
  • -datalog — get the datalog from the RCX and print it to stdout.
  • -datalog-full — same as -datalog but with more verbose output. the deluxe edition ✨
  • -near — set the IR port to short-range mode.
  • -far — set the IR port to long-range mode.
  • -watch time — set the RCX's clock to the specified time. if you use now, then the host's current time is used.
  • -firmware filename — downloads the firmware to the RCX. you'll need the official Lego RCX firmware from the CD-ROM — the current (and so far only) file is called firm0309.lgo. this will probably be necessary the first time you use your RCX, and whenever it's been without batteries for more than a few minutes. 🔋😭
  • -firmfast filename — same as -firmware, but at quad speed. requires the tower to be in near mode (see -near). if you have trouble getting the fast download to work, please revert to the older (and slower) method. speed is fun until it isn't 🛼
  • -sleep timeout — set RCX auto-shutoff timeout, in minutes. nap time 💤
  • -msg number — send IR message to RCX. the brick will respond to this just as it would a communication from another RCX.
  • -raw data — send an arbitrary packet to the RCX and print the reply (if any) to stdout. the data should be a hexadecimal string, with no spaces, zero-padded so that it is an even number of characters (although it may be an odd number of bytes). for example, to read the contents of variable 1, you could use -raw 120001. the bytecodes for raw messages can be found on web sites that document the RCX protocol. it's giving hacker mode 💀
  • -remote value repeat — send a repeating remote command to the RCX.
  • -clear — erase all programs and datalog from the RCX. it's giving factory reset, dramatic edition 🧹

🌈 ENVIRONMENT VARIABLES 🌈

  • RCX_PORT — sets the default serial port. see the -S option.
  • NQC_OPTIONS — specifies extra options to be inserted into the command line. for example, setting NQC_OPTIONS to -TScout would cause nqc to target the Scout by default. set it and forget it 💅
  • NQC_INCLUDE — specifies additional paths to search for include files. see also the -I option.

🎀 EXAMPLES 🎀

to compile foo.nqc, download the bytecode to program slot three, and make the RCX start executing it immediately:

nqc -d -pgm 3 foo.nqc -run

to just compile bar.nqc, resulting in bar.rcx:

nqc bar.nqc

to download bar.rcx to the RCX:

nqc -d bar.rcx

to set the IR tower to short-range mode and download the firmware at high speed:

nqc -near -firmfast firm0309.lgo

to compile /usr/share/doc/nqc/examples/test.nqc and print the resulting bytecode listing to the screen in human-readable format:

nqc -L /usr/share/doc/nqc/examples/test.nqc

(this should result in the following output under nqc 2.1.0:

*** Task 0 = main
000 pwr        ABC, 7                13 07 02 07
004 dir        ABC, Fwd              e1 87
006 InType     0, Switch             32 00 01
009 InMode     0, Boolean            42 00 20
012 out        A, On                 21 81
014 chkl       1 != Input(0), 14     95 82 09 01 00 00 fa ff
022 plays      0                     51 00
024 out        A, Off                21 41

)

🍓 FILES 🍓

older versions of nqc required a separate rcx.nqh or rcx2.nqh file. this is now integrated into the binary and no longer necessary, but for reference, rcx2.nqh is included with the package. (if you installed the RPM, try /usr/share/doc/nqc-2.1.0/rcx2.nqh). glow-up complete ✨

👑 SEE ALSO 👑

💀 BUGS 💀

none known. but be aware that Scout support is still preliminary and may change significantly. so like… proceed with caution bestie 🙈

nqc is Copyright (C) 1998-2000 David Baum and released under the terms of the Mozilla Public License. see the documentation included with the program for more details.

💜 AUTHOR 💜

the Not Quite C programming language and the nqc program were written and are maintained by Dave Baum. various contributions have been made by other people — a full list of these can be found on Dave's web site.

this man page was written by Matthew Miller (mattdm@mattdm.org), with extremely large amounts of borrowing from other NQC documentation. (we love a documented source trail 🫡)

and that's the whole page, bestie!! this was Version 2.1 r1: 19 Feb 2000, brought to you by the General Commands Manual 💖 compile responsibly, download your bytecode, and go make that brick do a little dance. periodt ✨👑💅

📦 where this page comes from