4cdcfc4591b0ef3226c91a2a5e1d54c10a2f08c4
[citadel] / appimage / README.txt
1 ****************************************************************************************
2 **  DO NOT RUN THE APPIMAGE BUILD ON A PRODUCTION MACHINE!  IT WILL ERASE YOUR DATA!  **
3 ****************************************************************************************
4
5 The tooling in this directory can be used to build an AppImage, the entire Citadel System
6 distributed as a single binary file.  Visit https://appimage.org/ to learn more about the
7 AppImage format and how it works.
8
9 Again, do NOT try to run this on your production machine.  For that matter, don't try to
10 run it on anything other than a dedicated build host.  It will ERASE /usr/local/citadel
11 and /usr/local/webcit during the build process.
12
13 If you're an end user you shouldn't have any need to do this at all.  The whole point of
14 this is that we can supply ready-to-run binaries that will run on any Linux/Linux system
15 without modification or dependencies.  If you are an end user, stop here, go download the
16 binary package, and use it.  Enjoy it and have fun.
17
18 Still with us?  Then you must be a new member of the Citadel team and you're packaging
19 the software for a new architecture or something.  So here's what you have to do to build
20 the binary:
21
22 1. Download the Citadel source tree (if you're reading this, you've already done that).
23 2. Install all system dependencies.  The same ones needed for Easy Install are fine.
24 3. Download and install "appimagetool" from appimage.org.
25 4. Run "./build_appimage.sh"
26
27 What's going to happen next?
28
29 1. Any existing /usr/local/citadel and /usr/local/webcit will be erased.
30 2. The script will go through the source tree, building and installing libcitadel,
31    the Citadel server, and WebCit into the /usr/local hierarchy.
32 3. All binaries, static data, and libraries will be copied into the citadel.AppDir
33    tree.
34 4. appimagetool will be called, and it will generate an executable with a
35    name like "Citadel-x64.AppImage".   This is your distributable binary.  Upload
36    it somewhere fun.
37
38 You should be running this build on the OLDEST version of Linux/Linux on which your
39 binary should be able to run.  The distribution does not matter -- for example, a
40 binary built on Debian should run fine on Ubuntu or Red Hat or whatever -- but the C
41 library and other very base system libraries are only upward compatible, not downward
42 compatible.  For example, at the time of this writing, I am building on Ubuntu 16 and
43 it's early 2021.