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.