INSTALL

   1
   2 BUILDING
   3 --------
   4 To make the binaries from the top directory, type
   5
   6      make
   7
   8 This will create the directories "./bin", "./lib", and "./font/compiled".
   9
  10 The compiled programs will be in the "./bin" directory.  The "./lib"
  11 directory will contain the file wcwidth.c, to provide an implementation
  12 of the POSIX wcwidth and wcswidth functions.
  13
  14 By default, simply typing "make" does not build the font.  To build the
  15 font, type
  16
  17      make BUILDFONT=1
  18
  19 The font will then build, placing files in the "font/compiled/" directory.
  20
  21 The default settings will build Unifont with four-digit hexadecimal
  22 glyphs appearing for unassigned code points, and with no glyphs for
  23 Private Use Area code points or non-printing code points.  As an
  24 example, to override these defaults in this top-level directory type
  25
  26      make BUILDFONT=1 UNASSIGNED="" PUA="plane00/pua.hex" \
  27           NONPRINTING="plane00/nonprinting.hex"
  28
  29 To make certain that no unassigned, PUA, or non-printing glyphs are
  30 included, type
  31
  32      make BUILDFONT=1 UNASSIGNED="" PUA="" NONPRINTING=""
  33
  34 You can similarly build Unifont with your own custom PUA glyphs.
  35 Just specify where the custom PUA file is, relative to the "font/"
  36 directory.  Note, though, that unifontpic generates its glyph
  37 diagram from whatever .hex files are in the "font/plane00" directory.
  38 Therefore, to have custom PUA glyphs be part of this generated
  39 glyph map, replace "font/plane00/pua.hex" with a custom pua.hex file.
  40
  41 Other useful make variables that can be overridden on the command line
  42 from the top-level Makefile include:
  43
  44      DESTDIR   - By default, not set; set to an alternate root location
  45                  such as "~/tmproot" if desired, but this directory
  46                  must already exist.
  47      USRDIR    - Set as typically "usr" or "usr/local" for installation
  48      PREFIX    - This is just $(DESTDIR)/$(USRDIR) but can be overridden.
  49      PKGDEST   - Destination for package files, by default "usr/share"
  50                  so that the README file, this INSTALL file, the ChangeLog
  51                  file, etc. will be installed in "/usr/share/unifont".
  52      COMPRESS  - Set to non-zero to compress installed man pages
  53
  54 All of the .hex file names can be replaced selectively on the top-level
  55 "make" command line.  The list of component hex file variables is:
  56
  57      UNIFONTBASE - The bulk of Unifont scripts
  58      CJK         - Most of the CJK Ideographs
  59      HANGUL      - Hangul Syllables block
  60      NONPRINTING - Glyphs for non-printing characters
  61      SPACES      - Space glyphs, single- and double-width
  62      UNASSIGNED  - Glyphs for unassigned code points
  63      PUA         - Glyphs for the Private Use Area
  64
  65 The files "doc/unifont.info" and "doc/unifont.pdf" are pre-generated
  66 as part of the distribution.  This is for the convenience of systems
  67 that do not have texinfo, texi2pdf, and TeX installed.  To rebuild
  68 these files from scratch (with texinfo, texi2pdf, etc. installed), type
  69
  70      cd doc
  71      make doc
  72      make clean
  73
  74 The "make clean" command removes intermediate files that texi2pdf creates.
  75
  76 To install the binaries, man pages, and Unifont, review the
  77 destination directories in the Makefiles to verify that the files
  78 will be installed where you want, and then type
  79
  80      make install
  81
  82 This installs programs in "/usr/bin" or "/usr/local/bin" (depending
  83 on the USRDIR setting in the top-level Makefile), installs PCF and
  84 TrueType fonts in the appropriate places, and places the following
  85 files in "/usr/share/unifont" or "/usr/local/share/unifont" (again
  86 depending on the USRDIR setting in the top-level Makefile):
  87
  88      ChangeLog.gz    - license information for this package
  89      combining.txt   - list of Unicode Plane 0 combining characters
  90      INSTALL.gz      - this INSTALL file
  91      NEWS.gz         - the main changes for each version
  92      README.gz       - the README file
  93      unifont.bmp     - 256-by-256 glyph graphic of Unifont
  94      unifont.info.gz - Texinfo tutorial on using the Unifont utilities
  95      unifont.txt.gz  - Texinfo tutorial on using the Unifont utilities
  96      unifont.hex     - composite Unifont .hex source, used by GRUB1
  97      wchardata.c     - implementation of IEEE 1003.1-2008 wcswidth and wcwidth
  98
  99 Typing "make install" will install font files from "font/compiled/"
 100 if that directory exists; otherwise it will install font files from
 101 the "font/precompiled/" directory.
 102
 103 To rebuild what is in the "font/precompiled" directory (which you
 104 ordinarily should never do--there would have to be a very good
 105 reason), remove its files, modify the DATE and VERSION information
 106 in the top-level Makefile and in "font/Makefile", then type
 107
 108      make BUILDFONT=1
 109      make precompiled
 110
 111 from the top-level directory or the "font/" subdirectory.
 112
 113 To just make the fonts, charts, etc. within the "font" directory,
 114 install the "bdftopcf" program and FontForge as well as performing
 115 a "make install" to install the Unifont binaries.  Then from the
 116 top-level directory type
 117
 118      cd font
 119      make BUILDFONT=1
 120
 121 The resulting fonts will be in the "./font/compiled" directory, along
 122 with bitmap renderings of each glyph.  Note that if you've changed
 123 glyphs, it might not be necessary to specify "BUILDFONT=1" but by
 124 setting that on the command line, it forces the build whether or not
 125 any glyphs have changed.
 126
 127 WARNING: Building the TrueType version of GNU Unifont will require
 128 anywhere from 256 MBytes to 1 GByte of virtual memory, can require
 129 almost 250 Megabytes of free disk space during the build, and is best
 130 run on a decent processor (say 1 GHz clock rate or better).
 131
 132 During the TrueType build, FontForge will monopolize your CPU...plan
 133 accordingly.
 134
 135 There is no reason to build the font from scratch unless you modify
 136 the .hex font source files (or must satisfy an insatiable curiosity),
 137 because the "./font/precompiled" directory already contains pre-built
 138 BDF, PCF, and TrueType fonts.
 139
 140 To create a custom version of the font with combining circles (similar
 141 to what was done to create the large picture of Unifont), type:
 142
 143      cd font/ttfsrc
 144      sort ../plane00/*.hex | \
 145           unigencircles combining.txt ../plane00/nonprinting.hex > unifont.hex
 146      make BUILDFONT=1
 147
 148 When "make" is finished, the ttfsrc directory will contain a "unifont.ttf"
 149 file which includes the dashed combining circles that the unigencircles
 150 utility added.  Copy this "unifont.ttf" file to a safe location in a different
 151 directory with a more descriptive name.  This font is named "unifont_sample-*.*"
 152 in the font distribution.  Then type
 153
 154      make clean
 155
 156 If you've made a new version of the font, hand-copy the new font file(s)
 157 to your desired destination.  Otherwise, precompiled PCF and TrueType
 158 versions of the font will be copied from "./font/precompiled/" into
 159 "$(DESTDIR)/usr/share/fonts".
 160
 161 After font installation, you might need to restart the X Window System
 162 for the new fonts to be recognized, but first try the command
 163
 164      xset fp rehash
 165
 166 in a shell (terminal) window.  If that doesn't work, restart the X
 167 Window System.
 168
 169 To remove intermediate files, from the top-level directory type
 170
 171      make clean
 172
 173 To remove all created files and leave the directory in its pre-build
 174 state, from the top-level directory type
 175
 176      make distclean
 177
 178 That will remove the "./bin" directory, the "./lib" directory, the
 179 "./font/compiled" directory, and other intermediate files.  Note that
 180 this command leaves the files in "./font/precompiled" intact, even
 181 though a prior "make precompiled" command would have rebuilt those files.
 182