annotate INSTALL @ 171:f736f3ce8310

fc-gsm2vm utility written
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 22 Mar 2017 18:21:03 +0000
parents cedd12ebf35a
children 4022bfbaafd4
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
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
26 3A: Become root just to create the /opt/freecalypso directory and chown it
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
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
29 4A: Run 'make install' as your regular uid; it should succeed because you
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
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
33 5A: You are done!
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
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 Building and installing the ARM7 toolchain
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 ==========================================
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 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
64 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
65 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
66 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
67 as follows:
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 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
70
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 binutils-2.21.1a.tar.bz2
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 gcc-core-4.5.4.tar.bz2
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 newlib-2.0.0.tar.gz
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 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
76 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
77
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 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
79 target-utils or Citrine.
0
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 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
82 *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
83 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
84
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 Compiling target-utils
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 ======================
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 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
89 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
90 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
91 '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
92 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
93
56
4213cf6536fa doc/Compiling: update for the move to /opt/freecalypso
Mychaela Falconia <falcon@freecalypso.org>
parents: 22
diff changeset
94 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
95 are needed only for development and only very rarely.