# HG changeset patch # User Mychaela Falconia # Date 1700604669 0 # Node ID bc3367755586683577269e901df2417f656f0f54 # Parent de3b299561b35b457c19aaf52025ed88eea61587 add INSTALL document diff -r de3b299561b3 -r bc3367755586 INSTALL --- /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 +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.