INSTALL.txt

   1 PREREQUISITES
   2
   3     Using GCC:
   4         Required
   5             * gcc          : GNU C compiler
   6             * GNU binutils : A collection of binary tools
   7             * GNU make     : make
   8             * sh           : POSIX type shell
   9             * GNU coreutils: Core utilities package (chmod, install, mkdir,
  10                              mv, rm, uname)
  11
  12         Optional (depending on build targets):
  13             * perl         : Practical Extraction and Report Language
  14                              perl >= 5.10.1 is required for rebuilding the
  15                              manual pages with pod2man.
  16                              perl >= 5.18 is required for rebuilding the
  17                              international manual pages correctly in HTML with pod2html.
  18                              Self-tests require module perl-Test-Simple.
  19             * gettext      : Framework to help GNU packages produce multi-
  20                              lingual messages.
  21             * po4a         : PO for anything, for rebuilding manuals.
  22             * groff        : GNU troff text formatting system, for
  23                              international messages and manuals.
  24             * ghostscript  : An interpreter for the PostScript language and
  25                              for PDF (ps2pdf)
  26
  27
  28     Using LLVM CLANG:
  29         Clang can be used as a drop-in replacement for gcc. Just add CC=clang to the make
  30         command line.
  31
  32
  33     Using Watcom C:
  34         Required
  35             * Open Watcom     : http://www.openwatcom.org/
  36             * Open Watcom V2  : http://open-watcom.github.io/open-watcom/    (git repo)
  37                                 http://sourceforge.net/projects/openwatcom/  (binaries download)
  38
  39
  40     Using Microsoft Visual C++:
  41         Required
  42             * Visual C++   : You can get a free community version via this web page:
  43                              https://www.visualstudio.com/vs/community/
  44                              Download Visual Studio for Windows Desktop. Visual C++ is part
  45                              of Visual Studio. Out of the box compilation for 64-bit
  46                              applications is supported since version 2012.
  47
  48
  49
  50 BASIC INSTALLATION
  51
  52     To build the program type:
  53
  54         make
  55
  56
  57     To run the self-tests type:
  58
  59         make check
  60
  61
  62     To strip the executables:
  63
  64         make strip
  65
  66
  67     To install:
  68
  69         make install
  70
  71
  72     Clean:
  73
  74         make clean
  75
  76
  77 SELF-TESTS
  78
  79     To run the self-tests you need a Perl installation including
  80     modules perl-Test-Harness and perl-Test-Simple.
  81
  82     To check the native Windows ports you need to run the tests in
  83     the MSYS2 shell.
  84
  85     To run the tests in a DJGPP environment you need to make sure
  86     that the bash shell is available (sh.exe). And you need to be
  87     in an environment that supports long file names (LFN), e.g. on
  88     32 bit Windows.
  89
  90
  91     To run the tests:
  92
  93         make test
  94
  95
  96     Via the make variable PROVE_OPT extra arguments can be given to
  97     the prove command. E.g.:
  98
  99         make test PROVE_OPT=--color
 100
 101
 102 INSTALLATION NAMES
 103
 104     By default the 'install' target will install the program in
 105     /usr/bin, the language files in /usr/share/locale
 106     and the man page in /usr/share/man. You can specify an
 107     installation prefix other than /usr by modifying the
 108     'prefix' variable. An Example:
 109
 110         make prefix=$HOME clean all
 111         make prefix=$HOME install
 112
 113
 114 DEBUG
 115
 116     A debug enabled build can be made by adding DEBUG=1
 117     to the make command. Example:
 118
 119         make clean install DEBUG=1
 120
 121     With debug enabled you can debug the source code in gdb.
 122
 123
 124 DEBUG MESSAGES
 125
 126     Extra debug messages can be enabled by adding DEBUGMSG=1
 127     to the make command. Example:
 128
 129         make clean install DEBUGMSG=1
 130
 131     With debug messages enabled dos2unix will print extra information
 132     about accessing the file system.
 133
 134
 135 NATIVE LANGUAGE SUPPORT
 136
 137     Native Language Support (NLS) is by default enabled.
 138     To disable NLS add ENABLE_NLS=. Example:
 139
 140         make clean install ENABLE_NLS=
 141
 142
 143 INTERNATIONAL MAN PAGES
 144
 145     Since dos2unix 6.0.5 all man pages are encoded in UTF-8, because even
 146     Western-European man pages may contain Unicode characters not supported by
 147     the Latin-1 (ISO-8859-1) character set.
 148
 149     Originally the Unix man system supported only man pages in Latin1 format.
 150     Although the world is moving to Unicode format (UTF-8) there is still a lot
 151     of Latin1 legacy around.
 152
 153     The English man page is a pure ASCII file and is readable on all platforms.
 154
 155     Non-English man pages are encoded in UTF-8. These do not show properly on
 156     old systems.  Man pages in UTF-8 format are shown properly on Linux. Not
 157     all roff implementations support UTF-8.
 158
 159     In order to show UTF-8 man pages properly on Cygwin with traditional man
 160     you need to do the following:
 161
 162     In /etc/man.conf, change the NROFF definition to use 'preconv'.
 163
 164         NROFF        /usr/bin/preconv | /usr/bin/nroff -c -mandoc 2>/dev/null
 165
 166     To view the man page set the correct locale. E.g. for Ukrainian:
 167
 168         export LANG=uk_UA.UTF-8
 169         man dos2unix
 170
 171     With man-db the manpages show correctly out of the box. Cygwin changed to
 172     use man-db in June 2014.
 173     Man-db is the default man system on the major Linux distributions.
 174
 175
 176 LARGE FILE SUPPORT
 177
 178     Large File Support (LFS) is by default enabled. This enables
 179     the use of 64 bit file system interface on 32 bit systems.
 180     This makes it possible to open files larger than 2GB on 32 bit
 181     systems, provided the OS has LFS support builtin.
 182     To disable LFS make the LFS variable empty. Example:
 183
 184         Disable LFS:
 185         make clean install LFS=
 186
 187     The gcc compiler from the mingw.org project does not support LFS.
 188     It is advised to use the mingw-w64 compiler tool chain for LFS on
 189     32 bit Windows.
 190
 191
 192 UNICODE SUPPORT
 193
 194     Unicode UTF-16 support is by default enabled for Windows and Unix.  To
 195     disable make the UCS variable (Universal Character Set) empty.
 196
 197         Disable Unicode:
 198         make clean install UCS=
 199
 200     Unicode UTF-16 is not supported by the DOS and OS/2 versions.
 201
 202
 203 UNICODE FILE NAME SUPPORT ON WINDOWS
 204
 205     Since version 7.3 dos2unix can read and write on Windows file names
 206     with Unicode characters. Prior to version 7.3 dos2unix could only open
 207     files with characters in the system ANSI code page.
 208
 209     To see if dos2unix on Windows has unicode file name support type dos2unix -V.
 210
 211     Unicode file name support on Windows is enabled by setting UNIFILE=1 in
 212     the makefile or on the make command line.
 213
 214     To disable Unicode file name support, make UNIFILE empty:
 215
 216         make UNIFILE=
 217
 218     Unicode file name support is by default enabled.
 219
 220     Dos2unix built with Watcom C is not able to display foreign characters
 221     correctly, even when option -D unicode is used. The correct file names
 222     are written though.
 223
 224
 225 DOCUMENTATION
 226
 227     Manual pages are generated from Perl POD files.
 228     To rebuild the man pages from POD type:
 229
 230         make maintainer-clean
 231         make man
 232
 233     Manuals in PDF format are by default not created.
 234     To create manuals in PDF format type:
 235
 236         make pdf
 237
 238     PDF generation requires GhostScript to be installed.
 239
 240
 241 WINDOWS 32 BIT PORT
 242
 243     Using Mingw <http://www.mingw.org>, or MinGW-w64
 244     <http://mingw-w64.sourceforge.net>.
 245
 246     I  advise to use mingw-w64, because mingw-w64 has support for
 247     Large File Support (LFS), and mingw doesn't. LFS is the ability to
 248     read/write files larger than 2GB or 4GB on a 32 bit operation system.
 249     LFS also makes processing files on network drives more reliable. I have
 250     had a problem report that output files were not always written when files
 251     on a network drive were concurrently processed. By switching from
 252     mingw to mingw-w64 the problem was solved.
 253     Earlier I got a problem report of accessing small files on a Windows
 254     network drive from Debian Linux. Here also the solution was LFS.
 255     Since dos2unix 6.0.4 (2013-12-30) I build the binary win32 packages
 256     with mingw-w64.
 257
 258     I am using the MSYS2 project <http://sourceforge.net/projects/msys2/>
 259     which includes the MinGW-w64 compiler.
 260
 261     The MSYS(2) environment is required for building dos2unix with MinGW(-w64).
 262
 263
 264     Type these commands to build with mingw(-w64):
 265
 266         make clean
 267         make
 268         make strip
 269         make install
 270
 271     Using Open Watcom:
 272
 273         wmake -f wccwin32.mak clean
 274         wmake -f wccwin32.mak
 275         wmake -f wccwin32.mak install
 276
 277     Using Microsoft Visual C++:
 278
 279         nmake /f vc.mak clean
 280         nmake /f vc.mak
 281         nmake /f vc.mak install
 282
 283
 284     The win32 binaries built with MinGW32 are packed with a patched version of
 285     MinGW's libintl-8.dll that has builtin support for relocation. See also
 286     http://waterlan.home.xs4all.nl/libintl.html and
 287     http://sourceforge.net/p/mingw/bugs/1808/
 288     The MSYS2 project has the relocation patch already included.
 289
 290
 291 WINDOWS 64 BIT PORT
 292
 293     To compile a version for 64 bit Windows, get the Mingw-w64 compiler
 294     <http://mingw-w64.sourceforge.net>.
 295     I am using the MSYS2 project <http://sourceforge.net/projects/msys2/>
 296     which includes the MinGW-w64 compiler.
 297
 298     The MSYS2 environment is required for building dos2unix with MinGW-w64.
 299
 300         make clean
 301         make
 302         make strip
 303         make install
 304
 305     Or use Microsoft Visual C++. Visual Studio Express supports
 306     out of the box C/C++ compilation for 64-bit applications since
 307     version 2012. Start an "x64 Cross Tools Command Prompt" and
 308     type:
 309
 310         nmake /f vc.mak clean
 311         nmake /f vc.mak
 312         nmake /f vc.mak install
 313
 314
 315 DOS PORT, 32 BIT
 316
 317     To compile a version for DOS, get the DJGPP compiler
 318     <http://www.delorie.com/djgpp/>, and use makefile djgpp.mak.
 319     DJGPP 2.03 gcc >= 4.6 seems to cause problems. Crashes of gcc itself,
 320     or crashing dos2unix binaries (seen in DOSBox and DOSEMU).
 321     Use DJGPP 2.03 gcc <= 4.5.3.
 322
 323     DJGPP 2.05 seems to produce correct binaries (I tried gcc 5.3.0).
 324
 325
 326         make -f djgpp.mak clean
 327         make -f djgpp.mak
 328         make -f djgpp.mak strip
 329         make -f djgpp.mak install
 330
 331     Cross compilation with djgpp.mak works out-of-the-box in Cygwin if
 332     you have djgpp-gcc-core installed. On Linux you can add CROSS_COMP=1
 333     to the command line.
 334
 335
 336     Or use Open Watcom
 337     Cross compiling from Windows 32 bit. This works.
 338
 339         wmake -f wccdos32.mak clean
 340         wmake -f wccdos32.mak
 341         wmake -f wccdos32.mak install
 342
 343
 344 DOS PORT, 16 BIT
 345
 346     To compile a version for DOS, use the Borland C compiler 3.1 or 4.0,
 347     and use makefile bcc.mak:
 348
 349         make -f bcc.mak clean
 350         make -f bcc.mak
 351
 352     Or use Open Watcom
 353
 354         wmake -f wccdos16.mak clean
 355         wmake -f wccdos16.mak
 356         wmake -f wccdos16.mak install
 357
 358
 359 OS/2 PORT
 360
 361     Using EMX
 362
 363         make -f emx.mak clean
 364         make -f emx.mak
 365         make -f emx.mak strip
 366         make -f emx.mak install
 367
 368     Open Watcom
 369
 370         wmake -f wccos2.mak clean
 371         wmake -f wccos2.mak
 372         wmake -f wccos2.mak install