FreeCalypso > hg > fc-usbser-tools

comparison INSTALL @ 107:bc3367755586 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
add INSTALL document
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 21 Nov 2023 22:11:09 +0000
parents
children
comparison
equal deleted inserted replaced
106:de3b299561b3 107:bc3367755586
1 Installation location
2 =====================
3
4 The present fc-usbser-tools package is part of the greater FreeCalypso software
5 family, therefore, these tools are designed to be installed in the
6 /opt/freecalypso directory hierarchy on your system. Changing this install
7 location is NOT ALLOWED: if you try to change it, you will break things, and I,
8 the author of this software, will not provide any help or support whatsoever to
9 anyone who seeks to change our fixed installation location.
10
11 More information on this topic is provided in this FC-family-global article:
12
13 https://www.freecalypso.org/hg/freecalypso-docs/file/tip/Install-location
14
15 Building and installing fc-usbser-tools
16 =======================================
17
18 In order to compile and install our tools, follow these steps:
19
20 1: Run 'make' as a regular user (not root) to compile the software.
21
22 2: Decide if you prefer to have the /opt/freecalypso directory and everything
23 under it to be owned by root or by your non-root uid.
24
25 If you prefer /opt/freecalypso to be root-owned:
26
27 3A: Run 'make install' as root; the install rule in the
28 Makefile will do mkdir -p /opt/freecalypso as its first step.
29
30 4A: You are done!
31
32 If you prefer /opt/freecalypso to be owned by your "regular" non-root uid:
33
34 3B: Become root just to create the /opt/freecalypso directory and chown it
35 to your non-root uid.
36
37 4B: Run 'make install' as your regular uid; it should succeed because you
38 should have made yourself the owner of /opt/freecalypso with full write
39 permission in the previous step.
40
41 5B: You are done!
42
43 Please refer to FC-family-global Install-location article for PATH instructions,
44 specifically the choice of either adding /opt/freecalypso/bin to your PATH or
45 creating symlinks for each installed FC program from one of your "standard" PATH
46 directories to /opt/freecalypso/bin.
47
48 libusb dependency
49 =================
50
51 All tools in the present package fundamentally, inherently require libusb.
52 More specifically, our tools are built on libusb-0.x API, consisting of <usb.h>
53 include header and -lusb link library pull-in - hence these are the actual
54 dependencies that need to be satisfied. On "modern" systems these pieces will
55 typically be provided by libusb-compat-0.1 package wrapping around libusb-1.x,
56 but in the spirit of Holy retrocomputing, really old systems can be used with
57 native libusb-0.1.
58
59 CC= and CFLAGS= selection
60 =========================
61
62 Our Makefile hierarchy is set up to build with CC=gcc and CFLAGS=-O2 by default.
63 If you need to change either or both of these selections, you can do it by
64 adding CC= and/or CFLAGS= on the make invokation line, for example:
65
66 make CC=mygcc CFLAGS="-g -O2 -whatever-options"
67
68 udev rules for USB device access
69 ================================
70
71 All tools in the present collection operate on FTDI and CP2102 devices at the
72 native USB level, bypassing the usual abstraction of ttyUSB. In order to access
73 these USB devices from userspace, one needs to either su to root for each
74 operation (very inconvenient), or create special udev rules that will grant the
75 necessary permissions to your "regular" non-root uid. The udev subdirectory of
76 the present source package contains a udev rules file that works on Mother
77 Mychaela's Slackware 14.2 system. I am absolutely NOT a udev expert, I don't
78 claim to understand it, but the present concoction is modeled after OpenOCD's
79 udev rules file, and it works at least for me.
80
81 Staged installs
82 ===============
83
84 As already explained above, our fc-usbser-tools need to be installed under
85 /opt/freecalypso on your system in order to function correctly, and this runtime
86 location is not changeable. However, some users have requested an ability to
87 do a staged install: have the 'make install' operation install the finished
88 tree of files in some staging location, with the expectation that it will be
89 subsequently moved to /opt/freecalypso by some other mechanism. One use case
90 that has been presented to us was automated building of binary distribution
91 packages on a build host where writing to /opt/freecalypso is not allowed.
92
93 If you need to make a staged install of this sort, you can do it like this:
94
95 make install INSTALL_PREFIX=/home/me/my-fc-staging-area
96
97 Please note that this INSTALL_PREFIX= scheme changes *only* the location where
98 'make install' will deposit the installable files; it does NOT change the
99 location where our programs will look for other programs and helper files: the
100 latter location is hard-coded as /opt/freecalypso in bazillion places throughout
101 our code base.