OMK template example applications print APP_VER_ID instead of common SW_VER_ID.
[rtems-devel.git] / rtems-omk-template / README.makerules
1 Description of OCERA Make System for CAN Components (OMK)
2 =========================================================
3
4 Important notice:
5 This make system uses features found in recent versions of GNU Make
6 program. If you encounter problems with package building,
7 check, that you use correct version of Make program.
8 The Make older than version 3.80, could not be used.
9 Even Make version 3.80 has annoying bug which causes
10 building fail with misleading message "virtual memory exhausted".
11 Please, upgrade to last version of Make (3.81beta1).
12 You can take it from GNU CVS or from our local copy
13
14 http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz
15
16
17 There is list of features which we want to solve with our makesystem:
18  - central Makefile.rules for most of subcomponents and components
19   (our CAN framework includes more libraries common with our other projects,
20    we need to separate some utility libraries etc.)
21  - the rules in more spread Makefiles are way to the hell,
22   (update for different kernel, RT-Linux etc would be nightmare in other case)
23  - make system should allow to freely move with cross-dependant components
24    without need to update users of moved component
25   (I hate somethink like -I../../sched/rtlshwq/include in CAN makefiles
26    for example. Component could be renamed to different name or version
27    could be added to name and all Makefiles in CAN would require to
28    be updated)
29  - make system should be able to compile mutually cross-dependant libraries
30    and should ensure, that change in one component sources or headers
31    would result in relink or rebuild in components linked against that library
32    or including modified header file
33  - make system has to enable compilation out of OCERA full source tree
34   (we would lost many users of particular components in other case)
35  - compile should be able to do all above work without need to install
36    any files before successful finish of build.
37  - because we use some libraries for RT-Linux build and userspace
38    build, we need to solve how to compile from same sources to both targets.
39  - the build system should allow to call make for particular source
40    subdirectory. Time of recursive make through all subdirectories is
41    unacceptable.
42  - make system should enable to build out of sources tree
43   (else clean or working with CVS sandbox gets fussy and simultaneous
44    multiple targets gets problematic)
45  - it would be good, if there would be possibility to make from read-only
46    media sources
47  - make system should store results of build in some separate directory
48    structure to simple install and testing
49  - Makefiles in sources directories should be simple
50
51 There is probably only one alternative fully supporting above requirements
52 and it is GNU Autoheader...Automake...Autoconf... system.
53 But it is complicated and requires big amount of support files.
54 It would be acceptable if it could be easily used for OCERA framework.
55 But there are important show stopper for that system:
56  - it would require deep revision of all OCERA CVS contents and agreement
57    on this would be problematic
58  - this system is not well prepared for dual compilation for Linux
59    and RT-Linux sub-targets. It would mean many changes in default
60    autoconf setup to support this. Probably simplest way would be
61    to rebuild GCC tool chain for something like i586-elf-rtlinux.
62    This would require even more space for OCERA development.
63
64 The problem calls for same solution, which would have minimal impact
65 on other components and would be elegant and would be maintainable
66 and small, because our main goal is components development and not
67 make systems development.
68
69 There is result of our trial. It is OMK make system.
70 The Makefile and Makefile.omk files should be in all source
71 directories. Common Makefile.rules file is required in the toplevel
72 sources directory. Alternatively this file could be moved
73 to link tree pointing into readonly media or can be anywhere
74 else if MAKERULES_DIR and SOURCES_DIR are specified.
75
76 Syntax of Makefile.omk files is for usual cases compatible
77 to Automake's Makefile.am descriptions. There are specific targets
78 for RT-Linux and Linux kernel related stuff
79
80 Makefile.omk user defined variables
81 # SUBDIRS          .. list of subdirectories intended for make from actual directory
82 # lib_LIBRARIES    .. list of the user-space libraries
83 # shared_LIBRARIES .. list of the user-space shared libraries
84 # kernel_LIBRARIES .. list of the kernel-space libraries
85 # rtlinux_LIBRARIES.. list of the RT-Linux kernel-space libraries
86 # include_HEADERS  .. list of the user-space header files
87 # nobase_include_HEADERS .. headers copied even with directory part
88 # kernel_HEADERS   .. list of the kernel-space  header files
89 # rtlinux_HEADERS  .. list of the RT-Linux kernel-space  header files
90 # bin_PROGRAMS     .. list of the require binary programs
91 # utils_PROGRAMS   .. list of the development utility programs
92 # kernel_MODULES   .. list of the kernel side modules/applications
93 # rtlinux_MODULES  .. list of RT-Linux the kernel side modules/applications
94 # xxx_SOURCES      .. list of specific target sources
95 # INCLUDES         .. additional include directories and defines for user-space
96 # kernel_INCLUDES  .. additional include directories and defines for kernel-space
97 # rtlinux_INCLUDES .. additional include directories and defines for RT-Linux
98 # default_CONFIG   .. list of default config assignments CONFIG_XXX=y/n ...
99
100 The Makefile is same for all sources directories and is only 14 lines long.
101 It is there only for convenience reasons to enable call "make" from
102 local directory. It contains code which locates Makefile.rules in actual
103 or any parent directory. With standard BASH environment it works such way,
104 that if you get into sources directory over symbolic links, it is able to
105 unwind yours steps back => you can make links to readonly media component
106 directories, copy Makefile.rules, Makefile and toplevel Makefile.omk,
107 adjust Makefile.omk to contain only required components and then call
108 make in top or even directories after crossing from your tree
109 to readonly media.
110
111 The system compiles all files out of source directories.
112 The actual version of system is adapted even for OCERA tree mode
113 if OCERA_DIR variable is defined in Makefile.rules
114
115 There are next predefined directory name components,
116 which can be adapted if required
117
118 BUILD_DIR_NAME = _build
119         prefix of directory, where temporary build files are stored
120 COMPILED_DIR_NAME = _compiled
121         prefix of directory, where final compilation results are stored
122 GROUP_DIR_NAME = yyy
123         this is used for separation of build sub-trees in OCERA environment
124         where more Makefile.rules is spread in the tree
125
126 Next directories are used:
127
128 KERN_BUILD_DIR   := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/kern
129         directory to store intermediate files for kernel-space targets
130 USER_BUILD_DIR   := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/user
131         directory to store intermediate files for user-space targets
132
133 USER_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include
134         directory to store exported include files which should be installed later
135         on user-space include path
136 USER_LIB_DIR     := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib
137         same for user-pace libraries
138 USER_UTILS_DIR   := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin-utils
139         utilities for testing, which would not probably be installed
140 USER_BIN_DIR     := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin
141         binaries, which should go into directory on standard system PATH
142         (/usr/local/bin, /usr/bin or $(prefix)/bin)
143
144 KERN_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include-kern
145         directory to store exported include files which should be installed later
146         on kernel-space include path
147 KERN_LIB_DIR     := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib-kern
148         same for kernel-pace libraries
149 KERN_MODULES_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/modules
150         builded modules for Linux kernel or RT-Linux system
151
152 There is more recursive passes through directories to enable
153 mutual dependant libraries and binaries to compile.
154 Next passes are defined
155
156 default-config .. generates config.omk-default or xxx-default configuration file
157 check-dir      .. checks and creates required build directories
158 include-pass   .. copyes header files to USER_INCLUDE_DIR and KERN_INCLUDE_DIR
159 library-pass   .. builds objects in USER_BUILD_DIR/<relative path> and creates
160                   libraries in USER_LIB_DIR
161 binary-pass and utils-pass .. links respective binaries
162                 in USER_{BIN,UTILS}_DIR directory. If some object file is missing
163                 it compiles it in  USER_BUILD_DIR/<relative path>
164 kernel-lib-pass .. builds libraries for kernel space targets
165 kernel-pass    .. builds kernel modules
166
167 The amount of passes is relatively high and consumes some time.
168 But only other way to support all required features is to assemble
169 one big toplevel Makefile, which would contain all components
170 and targets cross-dependencies.
171
172 Drawbacks of designed make system
173  - the system is not as fast as we would like
174  - it lacks Autoconf and configure extensive support for many systems
175    from UNIX to DOS and WINDOWS
176  - it does not contain support for checking existence of target libraries
177    and functionalities as GNU Autoconf
178  - it is heavily dependant on GNU MAKE program. But it would not be big
179    problem, because even many commercial applications distribute GNU
180    MAKE with them to be able to work in non-friendly systems
181  - the key drawback is dependence on recent MAKE version 3.80 and better
182    and even version 3.80 of MAKE has important bug, which has been
183    corrected in newer sources
184
185 The last point is critical. I have not noticed it first, because
186 I use Slackware-9.2 and it contains latest released version 
187 of MAKE (version 3.80).
188 The problem appears when I have tried to build bigger libraries.
189 There is bug in version 3.80, which results in misleading
190 error "Virtual memory exhausted". It is known bug with ID 1517
191
192     * long prerequisite inside eval(call()) => vm exhausted, Paul D. Smith
193
194 I have optimized some rules to not push memory to the edge,
195 but there could be still issues with 3.80 version.
196
197 I have downloaded latest MAKE CVS sources. The compilation required
198 separate lookup and download for .po files and full Autoheader... cycle.
199 I have put together package similar to release. Only ./configure --prefix=...
200 and make is required. CVS sources contains version 3.81beta1.
201 You can download prepared sources archive from
202
203   http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz
204
205 The archive contains even "make" binary build by me, which should work
206 on other Linux distributions as well. 
207 Older version of MAKE (3.79.x released about year 2000) found
208 on Mandrake and RedHat are not sufficient and do not support eval feature.
209 I do not expect, that Debian would be more up-to-date or contain fixes
210 to MAKE vm exhausted bug.
211
212 The local CTU archive with our CAN components prepared for inclusion
213 into OCERA SF CVS could be found in my "can" directory
214
215   http://cmp.felk.cvut.cz/~pisa/can/ocera-can-031212.tar.gz
216
217 The code should build for user-space with new make on most of Linux distros
218 when make is updated.
219
220 If you want to test compile for RT-Linux targets, line
221
222 #RTL_DIR := /home/cvs/ocera/ocera-build/kernel/rtlinux
223
224 in "Makefile.rules" has to be activated and updated
225 to point RT-Linux directory containing "rtl.mk".
226 There is only one library ("ulutrtl") and test utility compiled for RT-Linux
227 ("can/utils/ulut/ul_rtlchk.c").
228
229 The next line ,if enabled, controls compilation in OCERA project tree
230
231 #OCERA_DIR := $(shell ( cd -L $(MAKERULES_DIR)/../../.. ; pwd -L ) )
232
233 The LinCAN driver has been updated to compile out of source directories.
234
235 Please, check, if you could compile CAN package and help us with integration
236 into OCERA SF CVS. Send your comments and objections. 
237
238 The OMK system has been adapted to support actual OCERA configuration process.
239 I am not happy with ocera.mk mix of defines and poor two or three rules,
240 but OMK is able to overcome that.
241
242 The OMK system has integrated rules (default-config) to build default configuration
243 file. The file is named "config.omk-default" for the stand-alone compilation.
244 The name corresponds to OCERA config + "-default" if OCERA_DIR is defined.
245 This file contains statements from all default_CONFIG lines in all Makefile.omk.
246 The file should be used for building of own "config.omk" file, or as list
247 for all options if Kconfig is used.
248