--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/INSTALL	Tue Nov 21 22:11:09 2023 +0000
@@ -0,0 +1,101 @@
+Installation location
+=====================
+
+The present fc-usbser-tools package is part of the greater FreeCalypso software
+family, therefore, these tools are designed to be installed in the
+/opt/freecalypso directory hierarchy on your system.  Changing this install
+location is NOT ALLOWED: if you try to change it, you will break things, and I,
+the author of this software, will not provide any help or support whatsoever to
+anyone who seeks to change our fixed installation location.
+
+More information on this topic is provided in this FC-family-global article:
+
+https://www.freecalypso.org/hg/freecalypso-docs/file/tip/Install-location
+
+Building and installing fc-usbser-tools
+=======================================
+
+In order to compile and install our tools, follow these steps:
+
+1: Run 'make' as a regular user (not root) to compile the software.
+
+2: Decide if you prefer to have the /opt/freecalypso directory and everything
+   under it to be owned by root or by your non-root uid.
+
+If you prefer /opt/freecalypso to be root-owned:
+
+   3A: Run 'make install' as root; the install rule in the
+       Makefile will do mkdir -p /opt/freecalypso as its first step.
+
+   4A: You are done!
+
+If you prefer /opt/freecalypso to be owned by your "regular" non-root uid:
+
+   3B: Become root just to create the /opt/freecalypso directory and chown it
+       to your non-root uid.
+
+   4B: Run 'make install' as your regular uid; it should succeed because you
+       should have made yourself the owner of /opt/freecalypso with full write
+       permission in the previous step.
+
+   5B: You are done!
+
+Please refer to FC-family-global Install-location article for PATH instructions,
+specifically the choice of either adding /opt/freecalypso/bin to your PATH or
+creating symlinks for each installed FC program from one of your "standard" PATH
+directories to /opt/freecalypso/bin.
+
+libusb dependency
+=================
+
+All tools in the present package fundamentally, inherently require libusb.
+More specifically, our tools are built on libusb-0.x API, consisting of <usb.h>
+include header and -lusb link library pull-in - hence these are the actual
+dependencies that need to be satisfied.  On "modern" systems these pieces will
+typically be provided by libusb-compat-0.1 package wrapping around libusb-1.x,
+but in the spirit of Holy retrocomputing, really old systems can be used with
+native libusb-0.1.
+
+CC= and CFLAGS= selection
+=========================
+
+Our Makefile hierarchy is set up to build with CC=gcc and CFLAGS=-O2 by default.
+If you need to change either or both of these selections, you can do it by
+adding CC= and/or CFLAGS= on the make invokation line, for example:
+
+make CC=mygcc CFLAGS="-g -O2 -whatever-options"
+
+udev rules for USB device access
+================================
+
+All tools in the present collection operate on FTDI and CP2102 devices at the
+native USB level, bypassing the usual abstraction of ttyUSB.  In order to access
+these USB devices from userspace, one needs to either su to root for each
+operation (very inconvenient), or create special udev rules that will grant the
+necessary permissions to your "regular" non-root uid.  The udev subdirectory of
+the present source package contains a udev rules file that works on Mother
+Mychaela's Slackware 14.2 system.  I am absolutely NOT a udev expert, I don't
+claim to understand it, but the present concoction is modeled after OpenOCD's
+udev rules file, and it works at least for me.
+
+Staged installs
+===============
+
+As already explained above, our fc-usbser-tools need to be installed under
+/opt/freecalypso on your system in order to function correctly, and this runtime
+location is not changeable.  However, some users have requested an ability to
+do a staged install: have the 'make install' operation install the finished
+tree of files in some staging location, with the expectation that it will be
+subsequently moved to /opt/freecalypso by some other mechanism.  One use case
+that has been presented to us was automated building of binary distribution
+packages on a build host where writing to /opt/freecalypso is not allowed.
+
+If you need to make a staged install of this sort, you can do it like this:
+
+make install INSTALL_PREFIX=/home/me/my-fc-staging-area
+
+Please note that this INSTALL_PREFIX= scheme changes *only* the location where
+'make install' will deposit the installable files; it does NOT change the
+location where our programs will look for other programs and helper files: the
+latter location is hard-coded as /opt/freecalypso in bazillion places throughout
+our code base.