Browse code

rename rtf

Nat! authored on 14/08/2015 16:36:34
Showing 2 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,888 @@
0
+**Enterprise Object Generator  v1.7**
1
+
2
+*eogenerator* is a command-line tool for reading EOModel file(s) and generating
3
+EO classes from them, using a different method than Apple's EOModeler.  This
4
+approach allows all business logic to be implemented in the EO classes without
5
+fear of being overwritten later.  There is also support for having a custom
6
+superclass for the generated EO classes, and for generating Objective-C \#import
7
+statements correctly if EOModels related to each other reside in separate
8
+frameworks.
9
+
10
11
+
12
+Version 1.7 is built as a universal binary for Intel macs, fixes problems with
13
+Boolean attributes, adds character encoding parameters, and fixes a couple of
14
+other minor problems.
15
+
16
17
+
18
+To see the fetch specification and addObjectToBothSides... cover methods, look
19
+in the example EOGJavaSource.eotemplate (EOGObjCSource.eotemplate for
20
+Objective-C).
21
+
22
23
+
24
+EOModeler's EO generation is straightforward: it generates one class per
25
+EOEntity.  While this is fine for simple applications, it has a major limitation
26
+-- the generated code can't be edited, since a future code generation would
27
+overwrite the changes.  A common approach to this problem is to put all custom
28
+logic in categories, leaving the base classes free to be overwritten
29
+repeatedly.  However this also has some downsides: additional transient-type
30
+instance variables can't be added, the generated accessor methods can not be
31
+overridden easily, and of course it does not work at all with Java. Another
32
+approach is to not generate accessor methods at all, instead just using
33
+-valueForKey: and -takeValue:forKey: everywhere.  This has major downsides in
34
+that code is harder to read, it's a bit slower, scalar types can't be used, and
35
+a massive amount of compiler type-checking is lost.
36
+
37
38
+
39
+To get around these problems, *eogenerator* takes a different approach.  For
40
+each EOEntity, **two** classes are generated.  The first contains all the
41
+generated accessor methods and instance variables; it has a class name slightly
42
+different than the entity name and will be regenerated whenever its EOEntity has
43
+changed.  The second class is the actual EO class.  It is only generated the
44
+first time through, starting out as an empty subclass of the first. 
45
+
46
47
+
48
+As an example, if you have an *Employee* entity, *eogenerator* produces:
49
+
50
+\_Employee.java
51
+
52
+public class \_Employee extends EOGenericRecord (or EOCustomObject)
53
+
54
+Employee.java  (only if not present -- doesn't overwrite)
55
+
56
+public class Employee extends \_Employee
57
+
58
+Or, for Objective-C:
59
+
60
+\_Employee.h
61
+
62
+\@interface \_Employee : EOGenericRecord (or NSObject)
63
+
64
+\_Employee.m
65
+
66
+\@implementation \_Employee
67
+
68
+Employee.h (only if not present -- doesn't overwrite)
69
+
70
+\@interface Employee : \_Employee
71
+
72
+Employee.m (only if not present -- doesn't overwrite)
73
+
74
+\@implementation Employee
75
+
76
+This way, custom code can be placed in the "Employee" class without being
77
+overwritten, since only the "\_Employee" class is regenerated.  The accessor
78
+methods can be overridden while being able to call the super implementation, and
79
+instance variables can be added to the Employee class if desired.
80
+
81
+While the Employee class will not be overwritten thereafter, it will be
82
+"touched" (i.e. have its timestamp updated) whenever \_Employee is regenerated. 
83
+This is done to force a recompilation.  Read-only files will not be overwritten
84
+at all unless the -force flag is given.  A prefix for the generated class names
85
+other than the default "\_" can be given with the -prefix argument.
86
+
87
+(It has recently been pointed out to us that John Vlissides defined a design
88
+pattern called "Generation Gap" detailing this type of dual-class approach -- it
89
+can be found online at http://www.research.ibm.com/designpatterns/pubs/gg.html ,
90
+and apparently also in *Pattern Hatching: Design Patterns Applied* (chapter 3). 
91
+Thanks to Matt Shedlick for the pointer.)
92
+
93
+**Templates**
94
+
95
+The EO classes are produced using template files.  The default locations for
96
+finding the template files are the current directory, followed by the standard
97
+Library/Developer locations (which on MacOS X Server is
98
+\~/Developer/EOGenerator, \~/Library/EOGenerator, /Local/Developer/EOGenerator,
99
+/Local/Library/EOGenerator, /Network/Developer/EOGenerator, and
100
+/Network/Library/EOGenerator), followed by the directory containing the
101
+eogenerator binary.  These directories should contain *.eotemplate* files. 
102
+There are at least six files that are expected to be available, two each for
103
+Objective-C header, Objective-C source, and Java source files.  If versions
104
+exist in multiple search paths, the first one found is used.  The -templatedir
105
+command-line option allows adding more directories to the front of the search
106
+path.
107
+
108
+By default, the template files are named:
109
+
110
+JavaSourceEOF5.eotemplate
111
+
112
+JavaSourceEOF4.eotemplate
113
+
114
+JavaSourceEOF3.eotemplate
115
+
116
+JavaSourceEOF2.eotemplate
117
+
118
+JavaSubclassSourceEOF5.eotemplate
119
+
120
+JavaSubclassSourceEOF4.eotemplate
121
+
122
+JavaSubclassSourceEOF3.eotemplate
123
+
124
+JavaSubclassSourceEOF2.eotemplate
125
+
126
+JavaClientSourceEOF5.eotemplate
127
+
128
+JavaClientSourceEOF4.eotemplate
129
+
130
+JavaClientSourceEOF3.eotemplate
131
+
132
+JavaClientSubclassSourceEOF5.eotemplate
133
+
134
+JavaClientSubclassSourceEOF4.eotemplate
135
+
136
+ObjCHeader.eotemplate
137
+
138
+ObjCSource.eotemplate
139
+
140
+ObjCHeaderEOF3.eotemplate
141
+
142
+ObjCSourceEOF3.eotemplate
143
+
144
+ObjCSubclassHeader.eotemplate
145
+
146
+ObjCSubclassSource.eotemplate
147
+
148
+These templates produce source equivalent to that generated by EOModeler using
149
+the default Apple templates.  The templates for a specific version of EOF will
150
+be used by default on that platform.
151
+
152
+However, the default templates are more intended to work with minimum fuss out
153
+of the box, and do not necessarily represent the best programming practice.  For
154
+example, the default superclass is always EOCustomObject or EOGenericRecord\*,
155
+where it is usually better to define your own abstract superclass for your EO
156
+classes since a lot of abstract functionality can be added there.  For another
157
+example, these templates can be used to generate String constants for entity and
158
+attribute names, so that compile-time checked values can be passed into the
159
+various EOF APIs that require entity or attribute names.  Therefore, EOGenerator
160
+also supplies the following two files:
161
+
162
+EOGJavaSource.eotemplate
163
+
164
+MyGenericRecord.java
165
+
166
+These demonstrate how to put in a different EO superclass, generate String
167
+constants, generate typed creation methods, generate methods to call named fetch
168
+specifications with typed arguments, generate typed cover methods that invoke
169
+addObjectToBothSidesOfRelationshipWithKey(), and more.  It is usually a good
170
+idea to start with the above two files and customize from there rather than just
171
+use the default templates.  Note, however, that these templates will not work
172
+out of the box -- you have to make customized versions.  These templates are
173
+based on the WebObjects 5.x versions; you'll need to change them if you're using
174
+old EOF releases.
175
+
176
+Similarly, example Objective-C templates are provided (based on the WebObjects
177
+4.5.1 template).  The default Objective-C templates have the further problem of
178
+always doing \#import \<EOControl/EOControl.h\>, which is an extremely
179
+heavyweight header to be importing for each EO class (which has extra
180
+ramifications on Windows NT/2000).\*\*  The example templates show many of the
181
+same techniques as the example Java template, and also how to generate
182
+cross-framework \#imports correctly, and how to avoid \#importing too much.
183
+
184
+EOGObjCHeader.eotemplate
185
+
186
+EOGObjCSource.eotemplate
187
+
188
+Specific template files can be specified using the -sourceTemplate, 
189
+-headerTemplate, -subclassSourceTemplate, -subclassHeaderTemplate,
190
+-javaTemplate, and/or -subclassJavaTemplate flags.
191
+
192
+\* Many projects will want to use a custom abstract superclass instead, as it
193
+offers an easy way to implement behavior that affects all EOs.  For example, if
194
+there's a requirement to store all database fields in uppercase, you can
195
+implement validateValueForKey() to generically uppercase all String values that
196
+come through.  For Objective-C, you can implement reference counting with an
197
+instance variable instead of using NSObject's slower versions (sometimes a good
198
+idea since EOs are retained and released a lot).
199
+
200
+\*\* In general, many people feel that \#importing or \#including comprehensive
201
+header files "clutters" the namespace, i.e. you are more likely to have name
202
+conflicts in your code the more you \#import.  More practically, the
203
+preprocessor and compiler may have to do more work, slowing down compiles. 
204
+Precompiled headers solve the speed problem on OPENSTEP and MacOS X, but they
205
+don't work on Windows NT.  Worse, the NT linker isn't smart enough to unique
206
+debugging symbol information when it links multiple object files, so the more
207
+\#import's you have the bigger your .obj and .dll/.exe files are.  If \#import
208
+\<EOControl/EOControl.h\> is in every EO header file, that means that each EO
209
+class, plus any other source file that even indirectly \#imports an EO header
210
+(i.e. virtually all of them), will have entries for every single EOControl,
211
+Foundation, and ANSI C symbol in its object file.  Thus, the size of the final
212
+(unstripped) .dll/.exe will be huge, since it has lots of copies of each symbol
213
+entry.  This makes the linker use a lot more memory and temporary disk space,
214
+potentially making compiles go much slower.  In short, I feel it is better to
215
+limit the use of these comprehensive \#imports to being inside .m files only, if
216
+they're used at all.  The unfortunate downside is a lot of repetitive \#imports
217
+in each .m file.  It's probably useful to \#import a few specific EOControl and
218
+Foundation headers in the .h template file (or the custom superclass' .h file)
219
+to minimize this.
220
+
221
+**Template Formatting**
222
+
223
+The template files are implemented using the MiscMerge engine.  It is similar
224
+but more flexible than EOModeler's system, as (among other things) conditionals
225
+are allowed and it can be more easily extended.  Its usage should be fairly
226
+straightforward, but it has its peculiarities if you are picky about whitespace
227
+in the generated files.  See the included MiscMerge.rtf for a detailed
228
+description.
229
+
230
+The object used to drive the template engine is the EOEntity instance.  You may
231
+alter the template files and use methods associated with EOEntity to drive the
232
+output.  Most of the methods used are the same ones that Apple's templates use,
233
+which are implemented in EOModeler.framework.  *eogenerator* implements some
234
+additional methods that can be used, which can be found in FoundationAdditions.h
235
+and EOAccessAdditions.h.  Additionally, values that should be available to the
236
+templates can be specified on the command line using the -define-\<key\>
237
+parameter.
238
+
239
+Of particular note for Objective-C is the EOModel method **-frameworkName**. 
240
+The framework name is derived from finding the framework the .eomodeld is
241
+contained in, either by the PB.project file or a path component ending in
242
+".framework".  This information is then used by other EOEntity extension methods
243
+to generate cross-framework \#imports correctly.  While the framework name
244
+should be derived correctly in almost all cases, when necessary it can be set
245
+explicitly by putting the framework name under the "EOGeneratorFrameworkName"
246
+key in the EOModel's userInfo dictionary.
247
+
248
+**Please do not add timestamps to the templates!**  (Do not use the MiscMerge
249
+"date" command.)  Before a file is generated, it is compared byte-for-byte
250
+against the existing version of the file to determine if the file needs to be
251
+overwritten.  This is done to avoid needless recompilation of source files.  If
252
+there are timestamps used in the template, then the two versions of the file
253
+will always be different and it will be regenerated every time, causing needless
254
+compilations.
255
+
256
+**Invocation Options**
257
+
258
+There is only one required parameter to the program; the EOModel must be
259
+specified.  In most situations custom templates will be used, and if so these
260
+need to be specified as well.  The parameters can be can be used in full, or as
261
+substrings where unique (e.g. -destination can be specified as -d or -dest). 
262
+The order of options is not important.
263
+
264
+Only one kind of of classes can be generated at once.  If more than one type is
265
+needed (e.g. regular and client-side classes) then *eogenerator* must be invoked
266
+multiple times.
267
+
268
+\-objc
269
+
270
+Specifies that Objective-C source code files are to be generated.  This is the
271
+default for WebObjects 4.5 and earlier.
272
+
273
+\-java
274
+
275
+Specifies that Java source code files are to be generated.  Java is the default
276
+for WebObjects 5.x projects; Objective-C is the default with WebObjects 4.5 and
277
+earlier.
278
+
279
+\-javaclient
280
+
281
+Specifies that Java client source code files are to be generated, which use
282
+slightly different templates by default and could potentially have a different
283
+class name.  Implies -java.
284
+
285
+\-model *modelpath*
286
+
287
+Loads the EOModel found at *modelpath*, and generates classes for all entities
288
+found inside (unless specific entities are given on the command line).
289
+
290
+\-refmodel *modelpath*
291
+
292
+Loads the EOModel found at *modelpath*, but does not generate classes for its
293
+entities (unless specific entities are given on the command line, in which case
294
+this is the same as -model).  This is useful if you only want to generate
295
+entities for one model, but need to load other models to resolve all of the
296
+relationships in the main model.
297
+
298
+\-force
299
+
300
+Force overwriting of read-only files.  By default, read-only files will not be
301
+overwritten, and a warning message printed instead.  This can be a useful
302
+reminder in some revision control environments to check out the necessary files
303
+first.
304
+
305
+\-destination *destinationdirectory*
306
+
307
+Used to specify a destination directory for generated source code files.  By
308
+default, files are generated in the current directory*.*
309
+
310
+\-subclassDestination *destinationdirectory*
311
+
312
+Used to specify a destination directory for the empty subclass source code
313
+files.  This allows the generated files and the actively edited source to be
314
+placed in different directories.  By default, the subclass files are
315
+generated/looked for in the -destination directory*.*
316
+
317
+\-packagedirs
318
+
319
+When doing Java generation, creates directories corresponding to the Java
320
+package name components underneath the -destination directory.  This will
321
+generate the classes into a typical Java directory structure.  [Note that the
322
+old ProjectBuilder, still sometimes used on Windows, does not support classes
323
+laid out in this manner.  Xcode should not have this problem.]
324
+
325
+\-prefix *string*
326
+
327
+Uses string as the prefix for the generated class names (to distinguish them
328
+from the real EO class names).  By default this is a single underscore ( "\_"
329
+)*.*
330
+
331
+\-templatedir *directory*
332
+
333
+Prepends *directory* to the search path used to find template files.  Multiple
334
+-templatedir flags can be specified; the directories will be searched in the
335
+order they appear on the command line.
336
+
337
+\-sourceTemplate *file*
338
+
339
+\-headerTemplate *file*
340
+
341
+\-subclassSourceTemplate *file*
342
+
343
+\-subclassHeaderTemplate *file*
344
+
345
+\-javaTemplate *file*
346
+
347
+\-subclassJavaTemplate *file*
348
+
349
+Used to specify alternate template files to use.  *file* can be an absolute
350
+path, a relative path, or a filename found in one of the search path
351
+directories.  If not specified, the default templates are used*.*
352
+
353
+\-filenameTemplate *string*
354
+
355
+This argument causes *string* to be used as a MiscMerge template, with the
356
+result being used as the base name for the generated files.  Normally, filenames
357
+based on the entity's class name are used, which is sufficient for most
358
+situations.  Occasionally it can be useful to have custom filename patterns
359
+(coupled with custom templates), and this parameter can allow for a lot of
360
+flexibility.  For example, if you want Java interfaces to be generated along
361
+with the classes, a template of "{javaClassName}Interface" will cause
362
+\`Interface' to be appended to each filename. The delimiters for this template
363
+are \`{' and \`}', and the base object is the EOEntity instance (just like the
364
+regular class templates).  Regular EOEntity methods can be used as keys, as can
365
+entries in the userInfo dictionary.  When generating Java classes, if the
366
+generated filename has what looks like a Java package, it will override the
367
+package normally specified in the EOModel.
368
+
369
+The boolean variables "isSubclass" and "isSuperclass" are defined for use in if
370
+statements as necessary.  For example, to generate the abstract superclasses
371
+into a separate "eogen" subpackage, something like the following can be used
372
+(coupled with changes to the templates of course):
373
+
374
+\-filenameTemplate '{classPackageName}{if
375
+isSuperclass}.eogen{endif}.{classNameWithoutPackage}'
376
+
377
+\-encoding *enc*
378
+
379
+Specifies the character encoding to be used for generated files.  The name can
380
+be specified as a value returned from the NSString
381
++localizedNameOfStringEncoding: method, or (on MacOS X) an IANA name (typically
382
+what Java uses).  Defaults to the local platform string encoding.
383
+
384
+\-templateEncoding *enc*
385
+
386
+Specifies the character encoding to be used when reading template files.
387
+Defaults to the value specified for -encoding.
388
+
389
+\-define-*key value*
390
+
391
+This option adds the specified key-value pair to the list of variables available
392
+to the template, in addition to the EOEntity methods.  A key specified in this
393
+manner will **not** come before an EOEntity method of the same name when the
394
+template searches for the value.
395
+
396
+\-verbose
397
+
398
+Causes more verbose debugging output to be logged to standard output.
399
+
400
+\-version
401
+
402
+Displays the version number for *eogenerator*.
403
+
404
+\-help
405
+
406
+Displays the command line options available in *eogenerator*, with synopses of
407
+their purposes.
408
+
409
+By default, *eogenerator* generates all needed files for all entities in the
410
+EOModel, with the exception of entities defined to be EOGenericRecords and
411
+EOPrototypes entities.  If a smaller list of entities is desired, they can be
412
+specified on the command line:
413
+
414
+\$ eogenerator -model model.eomodeld Employee Organization Marketing
415
+
416
+Note that you are specifying the entity name.  Do not use the underscore name as
417
+the item to generate.  If one of these arguments contains the string ".eomodel",
418
+then -model is assumed.  If the name contains a \`\*' or \`?' character then the
419
+name is treated as a wildcard, matching any of the entity names in the models
420
+specified with -model (i.e., models specified with -refmodel are not searched). 
421
+The method underlying EOQualifier's "like" comparisons is used to do the
422
+matching.  Since the command shell will likely expand wildcards into filenames,
423
+the entity wildcard will probably have to be placed inside of double or single
424
+quotes (e.g.  "PW\*") to get passed to *eogenerator* correctly.
425
+
426
+As noted before, files are not overwritten if the generated contents matches the
427
+existing source code exactly.  This remains true even if entities are explicitly
428
+specified in the above manner.
429
+
430
431
+
432
+**Makefile Integration**
433
+
434
+The simplest way to integrate *eogenerator* into a project (unless you're using
435
+Xcode on MacOS X, see below) is typically to add rules to Makefile.postamble in
436
+the project where the .eomodeld lives, e.g.:
437
+
438
+EOGENERATOR = /path/to/eogenerator/binary
439
+
440
+EOGEN\_ARGS = -destination GeneratedEO.subproj \\
441
+
442
+             -subclassDestination .           \\
443
+
444
+             -java                            \\
445
+
446
+             -javaTemplate MyJava.eotemplate  \\
447
+
448
+             -subclassJavaTemplate MySubclassJava.eotemplate
449
+
450
+model1\_eos:
451
+
452
+\$(EOGENERATOR) \$(EOGEN\_ARGS) -model Model1.eomodeld -refmodel Model2.eomodeld
453
+
454
+model2\_eos:
455
+
456
+\$(EOGENERATOR) \$(EOGEN\_ARGS) -refmodel Model1.eomodeld -model Model2.eomodeld
457
+
458
+all\_eos:
459
+
460
+\$(EOGENERATOR) \$(EOGEN\_ARGS) -model Model1.eomodeld -model Model2.eomodeld
461
+
462
+Then add "model1\_eos", "model2\_eos", and "all\_eos" under the 'Build Targets'
463
+popup in ProjectBuilder's Build inspector for that project.  You will then be
464
+able to choose any of those targets from the Build panel.
465
+
466
+While we personally can't stand doing this, some people may want force EO
467
+regeneration every time the project is built.  To do this, further add a
468
+statement to Makefile.preamble:
469
+
470
+BEFORE\_PREBUILD += all\_eos  (or whichever rule name is desired)
471
+
472
+**Advanced Makefile Integration**
473
+
474
+If you don't mind getting complex, gnumake has several powerful features that
475
+can be very useful.  For instance, it's possible to search the paths named in
476
+the FRAMEWORK\_PATHS make variable (defined from settings in ProjectBuilder) to
477
+look for eomodels.  This makes use of a few of gnumake's string manipulation
478
+functions.
479
+
480
+\# Remove the "-F" in FRAMEWORK\_PATHS to get the list of paths
481
+
482
+MODEL\_PATHS := \$(subst -F,, \$(FRAMEWORK\_PATHS))
483
+
484
+\# Find the prototypes model in the specified path.  This is done by building
485
+
486
+\# a list of all possible paths (tack "Protos.eomodeld" after each path in
487
+
488
+\# MODEL\_PATHS), use the wildcard function to trim the list to the ones
489
+
490
+\# that actually exist, then take the firstword of the result in case there
491
+
492
+\# is more than one existing path.  This is a trick to do "search paths" using
493
+
494
+\# Makefile variables.  We actually try both directly in the framework
495
+directory,
496
+
497
+\# plus in the Resources of any .frameworks underneath it, in case the path
498
+
499
+\# is a framework project directory or is for installed frameworks.
500
+
501
+\#
502
+
503
+PROTO\_MODEL = \$(firstword \$(wildcard \$(foreach FPATH, \$(MODEL\_PATHS),
504
+\$(FPATH)/\*.framework/Resources/Protos.eomodeld \$(FPATH)/Protos.eomodeld)))
505
+
506
+\# Build both regular and client-side EOs
507
+
508
+build\_eos:
509
+
510
+\$(EOGENERATOR) -java -model MyModel.eomodeld -refmodel \$(PROTO\_MODEL)
511
+
512
+\$(EOGENERATOR) -javaclient -model MyModel.eomodeld -refmodel \$(PROTO\_MODEL)
513
+-destination ClientSideJava.subproj
514
+
515
+This trick can be wrapped inside an additional "foreach" to loop over a list of
516
+models:
517
+
518
+\# List of models to search for
519
+
520
+MODELS = Model1.eomodeld Model2.eomodeld Protos.eomodeld
521
+
522
+\# Use the search path trick to find list of models
523
+
524
+MODEL\_PATHS := \$(subst -F,, \$(FRAMEWORK\_PATHS))
525
+
526
+ALL\_MODELS = \$(foreach MODEL, \$(MODELS), \$(firstword \$(wildcard \$(foreach
527
+FPATH, \$(MODEL\_PATHS), \$(FPATH)/\*.framework/Resources/\$(MODEL)
528
+\$(FPATH)/\$(MODEL)))))
529
+
530
+\# Add "-refmodel" in front of each model
531
+
532
+REF\_MODELS = \$(foreach MODEL, \$(ALL\_MODELS), -refmodel \$(MODEL))
533
+
534
+\# Add the -refmodel flags to EOGEN\_ARGS
535
+
536
+EOGEN\_ARGS += \$(REF\_MODELS)
537
+
538
+\# Build the EOs for a Model3.eomodeld in the local directory
539
+
540
+build\_eos:
541
+
542
+\$(EOGENERATOR) \$(EOGEN\_ARGS) -model Model3.eomodeld
543
+
544
545
+
546
+**Xcode Integration**
547
+
548
+On MacOS X, WO 5 uses Xcode.app, which uses jam instead of gnumake as its
549
+underlying build tool.  The way jam is used precludes anything like
550
+Makefile.postamble, so you have to use the facilities settable in the UI.
551
+
552
+If you want the EO classes regenerated every build, then you can add a Shell
553
+Script Build Phase to your project to be run every build.  First create a shell
554
+script something like the following and put it in your project:
555
+
556
+\#!/bin/sh
557
+
558
+EOGENERATOR=/path/to/eogenerator/binary
559
+
560
+EOGEN\_ARGS=-destination GeneratedEO.subproj -subclassDestination . -java
561
+-javaTemplate MyJava.eotemplate -subclassJavaTemplate MySubclassJava.eotemplate
562
+
563
+\$EOGENERATOR \$EOGEN\_ARGS -model Model1.eomodeld -model Model2.eomodeld
564
+
565
+Then add the phase to the project:
566
+
567
+1) Choose the Targets tab in the left side of the window
568
+
569
+2) Select the main target and make sure it's active (has the check mark)
570
+
571
+3) Select Project-\>Edit Active Target from the menu
572
+
573
+4) Choose the Files and Build Phases tab
574
+
575
+5) Select the first phase listed, so there's a gray rectangle around the phase's
576
+box
577
+
578
+6) Select Project-\>New Build Phase-\>New Shell Script Build Phase from the menu
579
+
580
+7) Put in the shell to use (/bin/sh for the example above)
581
+
582
+8) Put in the script to execute -  \$SRCROOT/generateEO.sh for example. 
583
+(\$SRCROOT is defined by Xcode to be the project directory.)  NOTE: The contents
584
+of the shell script itself can be placed in here directly, instead of using an
585
+external shell script file.
586
+
587
+The EO files should now be regenerated every build.  Any new files that are
588
+created still have to be manually added to the project.   All of the project's
589
+build settings are available as environment variables, so your script can use
590
+those values if necessary.  These settings are basically the equivalent of the
591
+Makefile variables available under the old ProjectBuilder.
592
+
593
+If you don't want eogenerator to be run every time a build is done, then things
594
+get more interesting.  Xcode also allows you to have different Build Styles,
595
+which is essentially having alternate sets of build settings.  You could
596
+additionally add a new Build Style called "EOs", and add a GENERATE\_EOS setting
597
+with a value of YES.  Then, in the shell script used in the new build phase,
598
+check for that variable before running eogenerator:
599
+
600
+if [ "\$GENERATE\_EOS" = "YES" ] ; then
601
+
602
+    \$EOGENERATOR ...
603
+
604
+fi
605
+
606
+The script will still be run every time, but eogenerator won't.  From the
607
+command line, "pbxbuild -buildstyle EOs" will run with that build style (or you
608
+could just execute the script directly of course if project variables aren't
609
+used).
610
+
611
+It is also possible to add an entirely new target, however the only one that
612
+doesn't expect to actually build something is "Legacy Makefile", where you
613
+specify the build tool to run.  It may be possible to have the generateEO.sh
614
+script run as the build tool, but it seems as if an absolute path is required --
615
+plus, you lose all the build setting in the environment for the other targets. 
616
+You could actually use gnumake as the build tool here, create a Makefile, and
617
+put the eogenerator instructions there as in the old Project Builder.
618
+
619
+If anyone has any further ideas for ways to use eogenerator within the Xcode,
620
+please let us know.
621
+
622
623
+
624
+**Ant Integration**
625
+
626
+Using apache ant, eogenerator can be invoked using the standard "exec" task,
627
+something like the following:
628
+
629
+    \<target name="generate.eos"\>
630
+
631
+        \<exec dir="\${basedir}" executable="/path/to/eogenerator"
632
+
633
+              outputproperty="eogen.log" logError="true"\>
634
+
635
+            \<arg value="-model" /\>
636
+
637
+            \<arg file="\${basedir}/resource/MyModel.eomodeld" /\>
638
+
639
+            \<arg value="-refmodel" /\>
640
+
641
+            \<arg file="\${basedir}/resource/MyPrototypes.eomodeld" /\>
642
+
643
+            \<arg value="-templatedir" /\>
644
+
645
+            \<arg file="\${basedir}/buildresource/EOGenTemplates" /\>
646
+
647
+            \<arg value="-javaTemplate" /\>
648
+
649
+            \<arg value="MyJavaTemplate.eotemplate" /\>
650
+
651
+            \<arg value="-subclassJavaTemplate" /\>
652
+
653
+            \<arg value="MyJavaSubclassTemplate.eotemplate" /\>
654
+
655
+            \<arg value="-destination" /\>
656
+
657
+            \<arg file="\${basedir}/src" /\>
658
+
659
+            \<arg value="-packagedirs" /\>
660
+
661
+            \<arg value="-java" /\>
662
+
663
+            \<arg value="-define-copyrightYear" /\>
664
+
665
+            \<arg value="2005" /\>
666
+
667
+        \</exec\>
668
+
669
+        \<echo message="EOGenerator"/\>
670
+
671
+        \<echo message="\${eogen.log}"/\>
672
+
673
+    \</target\>
674
+
675
+Obviously, much use can be made of Ant's variable substitution, letting values
676
+like the models or templates be defined in external .properties files, etc.
677
+
678
679
+
680
+**Eclipse Integration**
681
+
682
+If you are using Eclipse for your project, you can set up EOGenerator as a
683
+"Builder" for your project.  These instructions are for Eclipse 3.0.1; the
684
+details may be slightly different in other Eclipse versions.
685
+
686
+1. Select the Project-\>Properties menu item.
687
+
688
+2. Select the "Builders" section and click the "New..." button.
689
+
690
+3. Choose "Program" as the type of external tool to create, not "Ant Build".
691
+
692
+4. In Location, put the path to the eogenerator executable.
693
+
694
+5. Put in the working directory you want; this makes it easier to use relative
695
+paths with any arguments. \${project\_loc} is a good value (this is a variable
696
+defined by Eclipse).
697
+
698
+6. Add any arguments, for example: -model resource/MyModel.eomodeld -refmodel
699
+resource/MyPrototypes.eomodeld -templatedir
700
+\${project\_loc}/buildresource/EOGenTemplates -javaTemplate
701
+MyJavaTemplate.eotemplate -subclassJavaTemplate
702
+MyJavaSubclassTemplate.eotemplate -destination \${project\_loc}/src -packagedirs
703
+-java -define-copyrightYear 2005
704
+
705
+7. Choose "Program" as the type of external tool to create, not "Ant Build".
706
+
707
+8. Under the "Refresh" tab, you may want to specify the folders to get refreshed
708
+after EOGenerator runs, so that Eclipse becomes aware of any new source files.
709
+
710
+9. Under the "Build Options" tab, you may wish to change when EOGenerator gets
711
+invoked.
712
+
713
+10. Click the OK button.  Back in the list of Builders, you can move EOGenerator
714
+above the regular Java Builder so it gets invoked before the regular Java
715
+compiler.
716
+
717
+Eclipse defines several other variables that can be used; click the
718
+"Variables..." button when defining the Location, Working Directory, or
719
+Arguments.  You can also define your own.
720
+
721
+Obviously, as an alternative you can just use Eclipse's Ant integration to
722
+invoke an ant target defined in build.xml (see Ant Integration above), which
723
+will also allow for building from the command line.
724
+
725
726
+
727
+**Feedback**
728
+
729
+We are very interested in any comments, suggestions, bug reports, or any other
730
+feedback on *eogenerator*; please send them to \<eogenerator\@rubicode.com\>.
731
+
732
+Mike Gentry, Carl Lindberg, and Doug McClure
733
+
734
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS \`\`AS IS'' AND ANY EXPRESS
735
+OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
736
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO
737
+EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, INDIRECT,
738
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
739
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
740
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
741
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
742
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
743
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
744
+
745
+(Or, the short version:  If it breaks, you get to keep the pieces. :-) )
746
+
747
748
+
749
+**History**
750
+
751
+1.7 Built as a universal binary for use on Intel Macs.
752
+
753
+Fixed Apple's buggy handling of Boolean attributes (Number attributes with a
754
+valueType of "c").  These should now be generated correctly as Boolean instead
755
+of Number.  Reported by Miguel Arroz.
756
+
757
+Added -encoding and -templateEncoding parameters to control character encoding
758
+of generated files and templates.  Suggested by Francis Labrie.
759
+
760
+Added enhancements to -filenameTemplate (isSubclass/isSuperclass variables) for
761
+more flexible filename generation.  Suggested by Stéphane Corthésy.
762
+
763
+Added -lastLetter NSString method for use in templates.  Suggested by Greg
764
+Hulands.
765
+
766
+Added barebones EOF headers to allow compilation with WebObjects 5.3. 
767
+Contributed by Mike Schrag.
768
+
769
+Fixed a bug that skipped JavaClient class generation if the server-side class
770
+was EOGenericRecord.  Reported by David Avendasora.
771
+
772
+Fixed WebObjects 5.2+ JavaClient generation when using entity inheritance. 
773
+Reported by David Avendasora.
774
+
775
+Added a log message in verbose mode when skipping EOGenericRecord entities.
776
+
777
+Avoided strange but harmless "EOControlJava RemoveMethodList..." log message
778
+which sometimes appeared.
779
+
780
+Updated with new MiscMerge; adds encoding support and fixes a few bugs.
781
+
782
+1.6 Fix problems with the 5.2.4 WebObjects release on MacOS X.  (The
783
+implementation for key-value coding is now in Foundation.framework, not
784
+EOControl.framework, and has a couple of implementation differences which caused
785
+us problems.)
786
+
787
+Added -filenameTemplate option for more flexible filename generation.  Suggested
788
+by Jason Jobe.
789
+
790
+Added usage message for -define-key option. 
791
+
792
+Added javaValueTypeClassName and javaScalarValueTypeClassName methods to help
793
+generate typed method signatures for attributes.
794
+
795
+Added initialLowercaseString string method.
796
+
797
+Reset the NEXT\_ROOT environment variable to blank so that it does not cause
798
+problems with EOAdapter frameworks loaded dynamically. Reported by Pierre
799
+Frisch.
800
+
801
+Fixed possible exceptions with the deleteAllXXXRelationships method defined in
802
+EOGJavaSource.eotemplate.  We were removing objects from an array during
803
+enumeration.
804
+
805
+Updated with new MiscMerge:
806
+
807
+Added setlocal, setmerge (was identify), setengine, and setglobal (was set)
808
+MiscMerge commands to set variables in different scopes.
809
+
810
+Added a debug command to print out information to stderr.
811
+
812
+Added ability to create arrays for use in places like foreach loops.
813
+
814
+Added in and notin operators for conditional expressions to check if something
815
+is in an array.
816
+
817
+1.5 On WebObjects 5.x systems, output now defaults to Java.
818
+
819
+Added support for WebObjects 5.2 (slightly changed templates).
820
+
821
+Added generation of methods to call named fetch specifications to the example
822
+templates.
823
+
824
+Added generation of relationship methods to call
825
+addObjectToBothSidesOfRelationshipWithKey to the example templates.  Suggested
826
+by Jonathan Rentzsch.
827
+
828
+Added MyGenericRecord.java as an example of a custom EO superclass.
829
+
830
+Fixed import statements in Java WO 5.x templates to conform to Apple's
831
+versions.  Reported by Eike Dierks.
832
+
833
+Updated to a new MiscMerge version; new features include break/continue and
834
+mathematical expressions.
835
+
836
+The generated classes are now declared as being abstract in Java.  Suggested by
837
+Joseph Leo Moreno.
838
+
839
+Avoid spurious "EOSchemaSynchronization" message being printed to console.
840
+
841
+1.4 Log explicit error message for failed model lookups.
842
+
843
+Added ability to specify the prefix used for the generated classes.  Submitted
844
+by Dominik Westner.
845
+
846
+Added -packagedirs option to generate classes under directories based on the
847
+Java package name.  Suggested by Emily Catherine Bach.
848
+
849
+Added EOGJavaSource example template.
850
+
851
+Added support for the all-Java WebObjects 5
852
+
853
+Added support for MacOS X 10.x
854
+
855
+Added Project Builder (MacOS X) integration instructions.  Submitted by David
856
+Teran.
857
+
858
+1.3 Added implementations of methods used in templates that are not in the
859
+standard frameworks -- EOModeler gets them from
860
+EOJavaClientExtensions.EOMBundle.  This caused accessor methods to never be
861
+defined in JavaClient generated classes.  Reported by Todd Thomas.
862
+
863
+Linked against EOJavaClient.framework so JavaClient generation will work with
864
+WOF 4.0.
865
+
866
+When generating JavaClient classes, make sure to use the clientClassName for the
867
+file name.  Reported by Todd Thomas.
868
+
869
+Will not overwrite read-only files, unless -force flag is given.
870
+
871
+Allow wildcards when specifying entity names.  Suggested by Rajnish Dogra.
872
+
873
+1.2 Added support for generating JavaClient classes.
874
+
875
+Fixed cosmetic whitespace errors in some of the Java templates.
876
+
877
+Made sure to ignore EOPrototypes entities, which aren't real entities.  Reported
878
+by William Swats.
879
+
880
+1.1 Added a JavaSubclassSourceEOF3.eotemplate, which is needed for Java projects
881
+using WOF 4.0, and fixed a crasher when the specified templates could not be
882
+found.  Reported by Richard Lewis-Shell.
883
+
884
+1.01 Fixed a typo in JavaSource.eotemplate, and class name errors in
885
+JavaSubclassSource.eotemplate.  Reported by Jim Roepcke.
886
+
887
+1.0 Initial release.
0 888
similarity index 100%
1 889
rename from README.rtf
2 890
rename to README.orig.rtf