annotate INSTALL @ 231:a58a7bbc0618

CHANGES: first changes since fc-host-tools-r5
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 03 Aug 2017 03:21:39 +0000
parents abe21d7b1226
children 9ab5c14e5b38
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 Building and installing FreeCalypso host tools
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 ==============================================
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
56
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
4 Our FreeCalypso host tools are designed to be installed in the /opt/freecalypso
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
5 directory hierarchy on your system. The author of this software is very
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
6 old-fashioned and refuses to use autotools (sorry, we aren't GNU), hence
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
7 various hard-coded paths under /opt/freecalypso are sprinkled in bazillion
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
8 places - thus changing this fixed install location is deemed to be impractical.
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
9
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
10 In order to compile and install our host tools, follow these steps:
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
11
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
12 1: Run 'make' as a regular user (not root) to compile the software.
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
13
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
14 2: Decide if you prefer to have the /opt/freecalypso directory and everything
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
15 under it to be owned by root or by your non-root uid.
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
16
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
17 If you prefer /opt/freecalypso to be root-owned:
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
18
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
19 3A: Run 'make install' as root; the install rule in the
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
20 Makefile will do mkdir -p /opt/freecalypso as its first step.
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21
56
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
22 4A: You are done!
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
23
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
24 If you prefer /opt/freecalypso to be owned by your "regular" non-root uid:
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
25
208
4022bfbaafd4 INSTALL: cosmetic fix in bullet point numbering
Mychaela Falconia <falcon@freecalypso.org>
parents: 58
diff changeset
26 3B: Become root just to create the /opt/freecalypso directory and chown it
56
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
27 to your non-root uid.
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
28
208
4022bfbaafd4 INSTALL: cosmetic fix in bullet point numbering
Mychaela Falconia <falcon@freecalypso.org>
parents: 58
diff changeset
29 4B: Run 'make install' as your regular uid; it should succeed because you
56
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
30 should have made yourself the owner of /opt/freecalypso with full write
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
31 permission in the previous step.
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
32
208
4022bfbaafd4 INSTALL: cosmetic fix in bullet point numbering
Mychaela Falconia <falcon@freecalypso.org>
parents: 58
diff changeset
33 5B: You are done!
56
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
34
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
35 The host tool binaries will be installed in /opt/freecalypso/bin; you can
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
36 either add this directory to your PATH or make symlinks from /usr/bin or
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
37 /usr/local/bin or wherever.
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
38
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
39 Dependencies
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
40 ============
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41
22
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
42 All FreeCalypso host tools are written in plain C, and with the exception of one
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
43 special hack-utility that has been excluded from the standard build set, they
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
44 have absolutely no library dependencies beyond libc. In other words, they are
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
45 very friendly to those who like bare bones minimalist systems. The only
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
46 exception is the fc-lcdemu hack which needs libX11 to compile and an X11 display
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
47 to run. It was a developer-only hack-utility to begin with, and the developer
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
48 setup of which it was a part never worked in a satisfactory manner, so it has
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
49 been retired. If you would like to play with it, you will need to compile it
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
50 separately, as it has been excluded from the top Makefile in order to have the
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
51 standard build set with no dependencies.
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52
22
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
53 The previous dependency on OpenSSL libraries for DES decryption of the factory
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
54 IMEI record on the Pirelli DP-L10 has been eliminated by incorporating our own
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
55 simple DES implementation (performance is not a concern for the one time
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
56 operation of retrieving the factory IMEI) into our rvinterf/etmsync source, and
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
57 the functions that require access to Pirelli's IMEI have now been integrated
aa20bdae9e53 doc/Compiling update: OpenSSL dependency eliminated, fc-lcdemu retired
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
58 into fc-fsio.
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59
212
abe21d7b1226 INSTALL: added blurb about target binaries in packaged releases
Mychaela Falconia <falcon@freecalypso.org>
parents: 208
diff changeset
60 Target binaries
abe21d7b1226 INSTALL: added blurb about target binaries in packaged releases
Mychaela Falconia <falcon@freecalypso.org>
parents: 208
diff changeset
61 ===============
abe21d7b1226 INSTALL: added blurb about target binaries in packaged releases
Mychaela Falconia <falcon@freecalypso.org>
parents: 208
diff changeset
62
abe21d7b1226 INSTALL: added blurb about target binaries in packaged releases
Mychaela Falconia <falcon@freecalypso.org>
parents: 208
diff changeset
63 If you are installing a packaged release of FreeCalypso host tools, there will
abe21d7b1226 INSTALL: added blurb about target binaries in packaged releases
Mychaela Falconia <falcon@freecalypso.org>
parents: 208
diff changeset
64 be a number of prebuilt target binaries (code to be run on the Calypso ARM7
abe21d7b1226 INSTALL: added blurb about target binaries in packaged releases
Mychaela Falconia <falcon@freecalypso.org>
parents: 208
diff changeset
65 processor) in the target-bin directory; when you run make install as instructed
abe21d7b1226 INSTALL: added blurb about target binaries in packaged releases
Mychaela Falconia <falcon@freecalypso.org>
parents: 208
diff changeset
66 above, these target binaries will be installed in /opt/freecalypso/target-bin.
abe21d7b1226 INSTALL: added blurb about target binaries in packaged releases
Mychaela Falconia <falcon@freecalypso.org>
parents: 208
diff changeset
67 Otherwise, you will need to compile them yourself using an ARM7 toolchain as
abe21d7b1226 INSTALL: added blurb about target binaries in packaged releases
Mychaela Falconia <falcon@freecalypso.org>
parents: 208
diff changeset
68 detailed below.
abe21d7b1226 INSTALL: added blurb about target binaries in packaged releases
Mychaela Falconia <falcon@freecalypso.org>
parents: 208
diff changeset
69
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 Building and installing the ARM7 toolchain
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 ==========================================
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 The current "official" GNU ARM toolchain for FreeCalypso consists of
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 binutils-2.21.1, gcc-4.5.4 and newlib-2.0.0 with a specific set of patches and
3
6a029ad28212 doc/Compiling: updated for the split between freecalypso-tools and Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
75 build configuration options. This toolchain is used to compile target-utils in
6a029ad28212 doc/Compiling: updated for the split between freecalypso-tools and Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
76 this package as well as our separately-maintained Citrine firmware. Build it
6a029ad28212 doc/Compiling: updated for the split between freecalypso-tools and Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
77 as follows:
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 1. Download these 3 source tarballs for the standard GNU+newlib components:
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 binutils-2.21.1a.tar.bz2
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 gcc-core-4.5.4.tar.bz2
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 newlib-2.0.0.tar.gz
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 2. Run the build+install.sh script in the toolchain directory. Read the
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 comments in the script first for the usage instructions.
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 The toolchain thus built will need to be in your PATH before you can compile
3
6a029ad28212 doc/Compiling: updated for the split between freecalypso-tools and Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
89 target-utils or Citrine.
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 Please note: the toolchain that is prescribed for FreeCalypso as above is
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 *believed* to be equivalent to the one used by OsmocomBB, but there are no
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 guarantees. Use any other toolchain at your own risk.
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 Compiling target-utils
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 ======================
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 Running 'make' in the target-utils tree with the ARM7 toolchain present in your
56
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
99 PATH will result in several target binaries being built, including compalstage
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
100 and loadagent which are needed in order to use FreeCalypso loadtools. Run
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
101 'make install' to install these target binaries in /opt/freecalypso/target-bin,
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
102 which is where loadtools will look for them.
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103
56
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
104 Run 'make all' in target-utils to build some additional target code pieces that
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
105 are needed only for development and only very rarely.