File: README.OSX

package info (click to toggle)
myodbc 3.51.09-1
  • links: PTS
  • area: main
  • in suites: sarge
  • size: 4,400 kB
  • ctags: 1,596
  • sloc: ansic: 29,806; sh: 10,765; cpp: 627; makefile: 610
file content (505 lines) | stat: -rw-r--r-- 16,135 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
+-------------------------------------------------------------+
| MyODBC                                                      |
| Mac OSX                                                     |
+-------------------------------------------------------------+

INTRODUCTION
---------------------------------------------------------------

These are my notes from my experiences building a binary MyODBC 
distribution on/for OSX. This was done during the last week in 
July 2004 with MyODBC v3.51.9. 


WHAT YOU NEED
---------------------------------------------------------------

OSX
---

I did my work on a modest iBook running a fresh install of OSX
10.3 (Panther) with a complete online update. 

Well; actually I had to reinstall everything after ending up 
with multiple ODBC systems on my OSX. Apple has not done a good 
job of taking charge of the core ODBC stuff so the driver 
vendors and others are all trying to lead it in various self 
serving directions and this sometimes results in redundent driver 
managers and drivers with all kinds of degradation of the user 
experience.

In the UNIX world libraries can be complicated by the fact that
there are different ways to handle share libraries. OSX adds more
complexity to this by also having 'Bundles' and 'Frameworks'.

Oh joy. I did not get too deep into Frameworks but Bundles are
important here.

Xcode
-----

I installed Xcode v1.1. This is the version which came with my 
OSX distribution. Its gcc with some GUI stuff.  

ODBC
----

My goal was to get things to work with the default ODBC 
environment. This is a version of iODBC built by
Apple - unfortunately this has many problems. I think it is 
preferrable to live with the problems and bug Apple to update 
ODBC in future releases than to install a new Driver Manager (as 
some are doing).

MySQL
-----

I used the latest general release - MySQL v4.0.20. I tried to 
use the binary distribution but failed to get MyODBC to build
against it properly. Seems it was fine for building a regular
share library but I was left with 4 or 5 unresolved references
when I tried to build a bundle. So I switched to using the
source tar-ball off of the web.

MyODBC
------

In the past I have built myodbc on OSX using the latest source
distribution but in this case I wanted to build directly from 
source in the source repository. In this case it is v3.51.9.

BUILDING 
---------------------------------------------------------------

Qt
--

MyODBC includes Windows specific GUI bits and Qt GUI bits. The
Windows specific can be found in the driver itself while on 
other platforms a seperate setup library is created using Qt.
This means we should install Qt when working on OSX. 

I will not repeat all of the Qt install documentation (see
www.trolltech.com) but here are a couple of tips.

1. Make sure you have your Qt environment variables set. I
   put the following in ~/.bashrc;

   export QTDIR=~/SandBox/qt-mac-free-3.3.2
   PATH=$QTDIR/bin:$PATH
   export PATH

   Since bash is not my default shell I enter bash as soon
   as I open an xterm using;

   $ bash

2. We want a static Qt lib so that we do not have to
   distribute any extra libraries so when you configure
   Qt I suggest doing the following;
 
   $ ./configure -static

Qt will take a long time to build. This tired old iBook
spent most of a day spinnings its bits.

MySQL
-----

I did not want to build or install the server parts - I just 
wanted the client stuff. I also wanted to link myodbc against
a static mysql client lib so I did the following;

$ ./configure --without-server --disable-shared
$ make
$ sudo make install

To provide the multi-threaded version of the mysql client I
did the following;

$ make clean
$ ./configure --without-server --disable-shared --enable-thread-safe-client
$ make
$ sudo make install

This resulted in MySQL client stuff being installed in 
/usr/local. In particular; the libs went into
/usr/local/lib/mysql and the header files went into
/usr/local/include/mysql and some other stuff into other places
in /usr/local.

MyODBC
------

I cloned the latest sources for myodbc from the source code
repository in the usual way. I had already removed some 
libtool files from the source tree in previous work so as
to ensure that the libtool on the build system gets used 
when building from source repository. The theory here is that 
if you have GNU auto-tools then you should have libtool. 
Unfortunately; OSX does not include libtoolize part of
libtool so I had to manually link in the systems libtool 
files. So I started with the following;

$ ln -s /usr/share/libtool/config.guess config.guess
$ ln -s /usr/share/libtool/config.sub config.sub 
$ ln -s /usr/share/libtool/ltmain.sh ltmain.sh

I then did the following to allow the gnu auto-tools a 
chance to create configure script and whatever other magic
it performs.

$ make -f Makefile.cvs 

NOTE: The above link steps are now in Makfefile.cvs
      so do "$ make -f Makefile.cvs osx".

Unfortunately myodbc could not find all of the mysql client
stuff so I had to help it along with a configure option.
So I did the following to start the build;

$ ./configure --with-mysql-path=/usr/local
$ make

This build process will fail because it lacks a config.h
needed by an odbc include file. I had the source for iodbc
(www.iodbc.org) laying around so I did a quick configure
in there (no build or install) and then copied the config.h 
to /usr/include. This is a hack but is probably safe for
my work here.

Starting myodbc make again will result in a link error. Seems
like adding a link option to the Makefile in the driver and
the driver_r dirs solves this problem. Unfortunately I could
not figure out the best way to add this properly to the gnu
auto build stuff nor am I certian this link option is the
best solution. But switching the link lines in those two
make files as follows seems to solve the link error;

LINK = $(LIBTOOL) --mode=link $(CCLD) $(AM_CFLAGS) $(CFLAGS) \
        $(AM_LDFLAGS) $(LDFLAGS) -Wl,-single_module -o $@

NOTE: Putting the "-Wl,-single_module" link option in other
      places on the link line may not work.

Now doing a make again will result in a complete build so
do the usual to install it. 

$ sudo make install

This drops some libmyodbc*dylib share libs into 
/usr/local/lib. You can do the following to see that the lib
type is the normal share library;

$ file /usr/local/lib/libmyodbc3-3.51.09.dylib

This will show "Mach-O dynamically linked shared library ppc".

This library will work under the following circumstances;

1. if you link your app (ie imyodbc) directly to the driver
2. using odbctest (not sure why this works and other stuff
   fails)

But it will fail to load under the following circumstances;

1. if you link your app (ie imyodbc) against the driver 
manager (which is the most common thing to do).
2. if you test with a standard GUI application such as
FileMaker v7.

So lets get rid of the files we just installed into
/usr/local/lib since they are not linked for use with the
driver manager. The following should do the job but your 
probably want to make sure you do not delete more files
than wanted.

$ sudo rm /usr/local/lib/libmyodbc*

Now lets link a bundle and place it in a better place (myodbcinst 
wants the drivers to be in /usr/lib).

$ cd driver/.libs
$ gcc -bundle -flat_namespace -o libmyodbc3-3.51.09.dylib *.o 
      -L/usr/local/lib/mysql -lmysqlclient -lz -liodbcinst
$ sudo cp -R *lib /usr/lib
$ sudo cp *la /usr/lib

Do the same for the multi-threaded version;

$ cd driver_r/.libs
$ gcc -bundle -flat_namespace -o libmyodbc_r3-3.51.09.dylib *.o 
      -L/usr/local/lib/mysql -lmysqlclient -lz -liodbcinst
$ sudo cp -R *lib /usr/lib
$ sudo cp *la /usr/lib

Now check the file type on this library;

$ file /usr/lib/libmyodbc3-3.51.09.dylib 

You should see "Mach-O bundle ppc". This should make the 
driver manager happy.

NOTE: I assume anyone wanting to link their app directly 
      to myodbc will have the skills to build an 
      appropriate myodbc share lib type from myodbc sources 
      so I simply replace the normal share library with the 
      bundle - with no intention of including the normal 
      share lib in a final myodbc binary distibution for 
      OSX.

setup
-----

Now make the setup library.

$ cd setup
$ qmake
$ make

This will produce libmyodbc3S.dylib (a standard share lib) 
and related symbolic links .tmp dir. You want these in 
/usr/lib so do the following;

$ cd .tmp
$ sudo cp -R lib* /usr/lib

NOTE: Ignore dl warnings - but these should get sorted 
      out at some point in the future. 

myodbcinst
----------

Ensure that you have the ODBC config files we are going
to use. They are;

~/Library/ODBC/odbcinst.ini
~/Library/ODBC/odbc.ini

If they are missing simply create empty ones. In 
anycase ensure that you have read/write privs. on
them.

Now make myodbcinst and use it to register the driver. The
location of the driver is hard-coded to /usr/lib so either
get the driver in /usr/lib or edit myodbcinst.

$ cd myodbcinst
$ make -f Makefile.osx
$ sudo myodbcinst -i
$ sudo myodbcinst -s

This will register the driver in;
~/Library/ODBC/odbcinst.ini 
and ensure that a sample DSN (myodbc) exists in;
~/Library/ODBC/odbc.ini

The DSN details may need to be edited to match your
environment. There are several ways to do this;

1. use a text editor to edit ~/Library/ODBC/odbc.ini
   (best choice at this point)
2. use gui ODBC Administrator (recommended after 
   install)
3. use "myodbcinst -e" to get a gui dialog (not best
   on OSX)
4. use MYODBCConfig to get gui dialog (recommended
   during install)

imyodbc
-------

Now make imyodbc by doing the following;

$ cd imyodbc
$ make -f Makefile.osx

MYODBCConfig
------------
 
Now make MYODBCConfig by doing the following;

$ qmake
$ make

This will result in MYODBCConfig.app in the current
dir. Execute this GUI app from an xterm with;

$ open MYODBCConfig.app
 
TESTING
---------------------------------------------------------------

myodbcinst
----------

This is a new addition to the myodbc source. This has been 
created to aid the driver installer. It can register/deregister
the driver and even add a sample data source name. Most 
importantly it does this using the standard installer ODBC API
so it *should* work regardless of the plaform and the ODBC 
system vendor.

dltest
------

This new addition to myodbc source is a tool which can be used 
to ensure that the driver can be explicitly loaded using 
libtool. It can also check for symbols (ie functions). 

This program is not part of the normal build process for myodbc
but can be easily built manually by going to the directory and 
running make with the appropriate makefile. For example;

$ make -f Makefile.osx 

NOTE: This is a good test for normal share library and seems to
      to be useful for the bundle type share library but I am not 
      sure that the default driver manager actually uses 
      libtool. This probably works well on OSX with the help of
      dlcompat. 

odbctest
--------

This is a standard feature of ODBC on OSX. It can be used to test
connecting to the server and submitting SQL to the server.

NOTE: odbctest can be used to test myodbc driver but the test
      may be somewhat misleading as odbctest seems to work fine
      with a normal lib type - but even a simple C test
      program will show that the driver manager fails to load
      such a library. So odbctest does some magic here. I
      even downloaded the sources for it and built it without
      being able to recreate this minor miracle.

imyodbc
-------

This new addition to myodbc source is a tool like the mysql 
command-line tool but is based soley upon ODBC calls. Use this to
test connecting to the server and submitting SQL to the server.

This can be linked directly to the driver or to the driver manager
providing more testing options.

This program is not part of the normal build process for myodbc
but can be easily built manually by going to the directory and 
running make with the appropriate makefile. For example;

$ make -f Makefile.osx

By default; this will link against the driver manager. Do the
following to link directly against the driver (you may need the
driver built as a standard library for this);

$ make -f Makefile.osx todriver


INSTALLER 
---------------------------------------------------------------

Copy the osx/MyODBC dir to some place like you home dir. 

Go into the MyODBC/resources dir and update the html files as 
needed - which means the version number at least.

Got into each dir in the MyODBC/root dir nd check for any 
BillOfMaterials.txt files. Where found; copy appropriate
files to the dir and then remove the BillOfMaterials.txt file.
You also want to remove and hidden dirs and files and the
SCCS dirs wherever they are found in MyODBC.

Now open the mac-install.pmsp  like this; 

$ open mac-install.pmsp

Edit the "Files" and "Resources" tabs to reflect your 
environment.

Then do File -> Create Package. Create the file as;

MyODBC-ver-OSX.pkg

Note that the a pkg file is actually a dir - which is not
suitables for distribution. Put this dir into a new dir and 
include any addiotional reamde as needed in there as well.
Then use "/Applications/Utilities/Disk Utility.app" to create
a disk image (dmg file).

MORE TESTING
---------------------------------------------------------------

Well start testing install by trying on current machine. Delete
the working files - which would be something like;

$ sudo rm /usr/lib/libmyodbc*
$ sudo rm /usr/bin/*myodbc*
$ sudo rm ~/Library/ODBC
$ sudo rm -r /Library/Receipts/MyODBC*

NOTE: The above is, in practice, an uninstall.

Now open the dmg and the pkg in the usual fashion.

Complications
-------------

- its is very possible that non-standard and even multiple
ODBC systems can be installed on OSX which complicates
things in a variety of ways - perhaps most notably in that the
ODBC config files may exist in different places and with diff
editing rules. For example; FileMaker v7 comes with DataDirect
ODBC drivers AND a Driver Manager of some sort.
 
- standard installer API calls do not create config dirs/files,
they are however created by ODBC Admin gui and can then be 
updated using ODBC installer API

- the default ODBC installer on OSX does not try to call 
the drivers ConfigDSN()

RECOMMENDATIONS
---------------------------------------------------------------

1. Need GNU auto-tools expert to work with OSX platform 
   specialist (someone who really knows gcc/ld/libtool well would 
   also do) to;
   - ensure that the driver is linked correctly. ie no 
   manual editing of make files after configure.
   - address link warnings

2. Need GNU auto-tools expert to overcome following problems;
   - need for iodbc config.h
   - using libtoolize where it exists and otherwise linking
     libtool files into source dir

3. Need graphics/web/UI person to jazz up installer and GUI
   bits.

4. Need to lean on Apple to make FileMaker use default ODBC
   system and to make some other enhancements fixs in ODBC;
   - make calls to ConfigDSN() if driver has it
   - make installer API create ODBC config files (ini files)
     not just the ODBC Admin GUI.
   - and many other non-conformance issues and bugs (see 
     source code - search for OSX conditions)

5. Possibly create a custom installer which can install, uninstall 
   and configure myodbc. This can be good for a number of reasons;
   - myodbcinst, used in PackageMaker install, does not have a 
     window handle to give ConfigDSN() so no GUI can be provided 
     to allow user to tweek their first DSN during install. They
     muust find and run the ODBC Admin tool after the install.
   - PackageMaker does not seem to allow for an uninstall?
   - the installer can be more intelligent and look nicer
 
Finally; OSX Users demand the best User experience from their 
products but with ODBC - things fall short of great. A
lot can be done to improve this and make it easier for OSX Users,
many of which are web developers or otherwise use mysql. 

---
Peter Harvey
August 2004