FreeCalypso > hg > fc-usbser-tools

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