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