home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / harbb30g.zip / DOC / gmake.txt < prev    next >
Text File  |  1999-09-17  |  7KB  |  229 lines
  1. #
  2. # $Id: gmake.txt,v 1.8 1999/09/16 23:52:04 dholm Exp $
  3. #
  4.  
  5. INTRODUCTION
  6. ============
  7.  
  8. This file explains the philosophy for the GNU-make based build system
  9. for Harbour, and gives instructions on how to use it.
  10.  
  11.  
  12. PHILOSOPHY
  13. ==========
  14.  
  15. This build system is based on GNU-make, the idea being that GNU-make
  16. is freely available for every platform you can dream up, and it is
  17. usually more powerful than any native make.
  18.  
  19. Each directory in the project contains one makefile, called Makefile,
  20. which lists the data (file names, directory names, etc.) that is used
  21. to determine how to bring ever target up to date within that
  22. directory. There are no rules in the Makefiles, to keep them
  23. platform-independent. The rules itself are included from the
  24. "appropriate" configuration file.
  25.  
  26. For example, this could be the Makefile for the VM library:
  27.  
  28. --  Cut here  ---------------------------------------
  29. #
  30. # $Id: gmake.txt,v 1.8 1999/09/16 23:52:04 dholm Exp $
  31. #
  32.  
  33. ROOT = ../../
  34.  
  35. C_SOURCES=\
  36.         dynsym.c \
  37.         hvm.c \
  38.         initsymb.c \
  39.  
  40. LIB=vm
  41.  
  42. include $(TOP)$(ROOT)config/lib.cf
  43. --  Cut here  ---------------------------------------
  44.  
  45. What this means is:
  46.  
  47. * The root of the source directory is in ../../; that is where the
  48.   config/ directory lives, with all the real rules to make the
  49.   targets.
  50. * The only sources in this directory are C sources (three files).
  51. * The library name is "vm". This will be translated to a real file
  52.   name depending on the rules file: "libvm.a" on Unix, "VM.LIB" on
  53.   DOS.
  54. * The final line includes the rules file. In this case, we include a
  55.   set of rules to build a library.
  56.  
  57. Let's look at another Makefile, this one for the Harbour compiler:
  58.  
  59. --  Cut here  ---------------------------------------
  60. #
  61. # $Id: gmake.txt,v 1.8 1999/09/16 23:52:04 dholm Exp $
  62. #
  63.  
  64. ROOT = ../../
  65.  
  66. YACC_SOURCE=harbour.y
  67.  
  68. LEX_SOURCE=harbour.l
  69.  
  70. C_SOURCES=\
  71.         genobj32.c \
  72.  
  73. C_MAIN=harbour.c
  74.  
  75. include $(TOP)$(ROOT)config/bin.cf
  76. --  Cut here  ---------------------------------------
  77.  
  78. Notice how we now have other kinds of source files: yacc sources and
  79. lex sources. Also, since this is a Makefile for a stand-alone
  80. executable, we indicate the name for the file containing the "main"
  81. function, which also defines the executable name. The rules included
  82. in this Makefile are those appropriate to build a stand-alone binary.
  83.  
  84. One final Makefile, this one from the source directory:
  85.  
  86. #
  87. # $Id: gmake.txt,v 1.8 1999/09/16 23:52:04 dholm Exp $
  88. #
  89.  
  90. --  Cut here  ---------------------------------------
  91. ROOT = ../
  92.  
  93. DIRS=\
  94.         compiler \
  95.         hbpp \
  96.         rtl \
  97.         vm \
  98.         rdd \
  99.         tools \
  100.  
  101. include $(ROOT)config/dir.cf
  102. --  Cut here  ---------------------------------------
  103.  
  104. This Makefile is used to traverse the subdirectories hanging from the
  105. current directory. It simply lists all the subdirectories to be
  106. traversed.
  107.  
  108. Now. let's take a look at the rules themselves. They all live in the
  109. config/ directory, with the following structure:
  110.  
  111.   config/: The generic configuration files.
  112.   config/win32: Configuration files for win32 platforms.
  113.  
  114.  
  115. Finally, you will notice one thing: the build system compiles
  116. everything into a subdirectory (for example, win32/gcc for WIN32 files
  117. compiled with gcc). This has two advantages:
  118.  
  119. 1. It allows you to compile for multiple platforms/compilers at the
  120.    same time.
  121. 2. It creates all temporary, object, binary, intermediate, etc. files
  122.    in the subdirectory; cleaning up is very easy.
  123.  
  124.  
  125. USAGE
  126. =====
  127.  
  128. To use the system, you need to install GNU-make 3.75 or later in your
  129. system. To check this, type "make -v"; you should see
  130.  
  131.   GNU Make version 3.75, by Richard Stallman and Roland McGrath.
  132.   ...
  133.  
  134. Then, you must set a couple of environment variables that indicate
  135. your architecture and compiler.
  136.  
  137. For gcc on Win95/WinNT with the Cygwin library:
  138.   HB_ARCHITECTURE   win32
  139.   HB_COMPILER       gcc
  140.  
  141. For gcc on Win95/WinNT with the Mingw32 library:
  142.   HB_ARCHITECTURE   win32
  143.   HB_COMPILER       mingw32
  144.  
  145. For MSVC on Win95/WinNT:
  146.   HB_ARCHITECTURE   win32
  147.   HB_COMPILER       msvc
  148.  
  149. For GCC on Linux:
  150.   HB_ARCHITECTURE   linux
  151.   HB_COMPILER       gcc
  152.  
  153. For GCC on OS/2:
  154.   Note: You must point C_INCLUDE_PATH to the EMX include directory and
  155.         you must also point LIBRARY_PATH to the EMX library directory.
  156.   HB_ARCHITECTURE   os2
  157.   HB_COMPILER       gcc
  158.  
  159. For IBM Visual Age C++ on OS/2:
  160.   Note: You must create an empty unistd.h in the IBMCPP\INCLUDE directory.
  161.   HB_ARCHITECTURE   os2
  162.   HB_COMPILER       icc
  163.  
  164. For Borland C++ 3.1
  165.   HB_ARCHITECTURE   dos
  166.   HB_COMPILER       bcc31
  167.  
  168. For DJGPP (GCC port for DOS)
  169.   HB_ARCHITECTURE   dos
  170.   HB_COMPILER       djgpp
  171.  
  172. For Watcom C/C++ 10.x (default Makefile creates DOS4G extender executables)
  173.   HB_ARCHITECTURE   dos
  174.   HB_COMPILER       watcom
  175.   Note: It is possible that you will have to increase the space reserved for
  176.         DOS environment variables in order to successfuly run make utility
  177.         (Add for example:
  178.      SHELL=C:\COMMAND.COM C:\ E=2048 /P
  179.      to your CONFIG.SYS )
  180.  
  181. If you issue a "make install", it will try to install your header,
  182. executable and library files into directories given by
  183.  
  184.   HB_BIN_INSTALL
  185.   HB_LIB_INSTALL
  186.   HB_INC_INSTALL
  187.  
  188. You can set those as environment variables too.
  189.  
  190. The most used targets are these:
  191.  
  192. * all: Same as typing "make" without arguments. It will usually try to
  193.   compile and link the obvious target in the directory.
  194.  
  195. * clean: Clean up everything made by make.
  196.  
  197. * install: Install stuff into the appropriate directories.
  198.  
  199.  
  200. NOTES
  201. =====
  202. In order to get a clean build after making source changes or after
  203. receiving updated source files, you must use the following two steps:
  204.  
  205. 1) make -r clean
  206. 3) make -r
  207.  
  208. Without the first step, changes to the Harbour compiler and/or various
  209. include files will not be reflected in any object modules created from
  210. Harbour source code.
  211.  
  212. The -r option isn't strictly necessary, but it does signficantly reduce
  213. the number of rules that make has to evaluate otherwise, which may give
  214. a performance boost on a slow system.
  215.  
  216.  
  217. To rebuild only a part of Harbour, go to the appropriate source directory
  218. and then run 'make -r'. For example, to rebuild all of Harbour, but not
  219. the test programs, change to the 'source' directory. To rebuild only the
  220. test programs, change to the 'test' directory.
  221.  
  222.  
  223. If you are using a DOS-based operating system, then you can build any
  224. program in tests/working by using the build batch file. For example,
  225. 'build scroll' will rebuild the scroll.prg program and then run it. This
  226. can also be used for modules that aren't in the Makefile. You can also
  227. pass parameters to the program. For example, 'build readfile harbour.ini'
  228. will rebuild the readfile.prg program and run it with 'harbour.ini' as a
  229. command line parameter.