File: README.osx

package info (click to toggle)
myodbc 3.51.11-6.1
  • links: PTS
  • area: main
  • in suites: etch, etch-m68k
  • size: 5,056 kB
  • ctags: 1,933
  • sloc: ansic: 31,656; sh: 10,955; cpp: 2,439; makefile: 1,120
file content (629 lines) | stat: -rw-r--r-- 20,733 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
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
+-------------------------------------------------------------+
| Connector/ODBC                                              |
| Apple 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. 

NOTE 3.51.10: Notes like this indicate modifications made to
              this document derived from building MyODBC
              3.51.10 distribution. This was done Nov.04.

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. 

NOTE 3.51.10: Now using a G5 single 1.8 Ghz.

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.

On OSX there is a functional difference between a share 
library built to simply share code in memory and a share
library built to be explicitly loaded by an application (or
another library) to provide plugin capabilities. A simple 
share library is called MH_DYLIB, uses the "dylib" file
extension and may not be loaded explicitly by other code.
A plugin library is called MH_BUNDLE, uses an undefined 
file extension (usually "bundle" or "so") and is created
specifically to be used as a plugin. The implication for
MyODBC is that we want to, by default, build the driver
and the setup library as bundles so that the driver manager
may load them explicitly. We also want to provide a means
to build the driver as a MH_DYLIB or static library in the
case where an app needs to link directly to the driver.


Xcode
-----

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

NOTE 3.51.10: Now using xcode v1.5.

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.

NOTE 3.51.10: Built with MySQL 4.1.7. The binary distro would
              probably work fine except it has a hard-coded
              relative path for zlib in mysql_config so I use 
              the source.

NOTE 3.51.11: Built with MySQL 4.1.9.

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. 


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 a terminal window 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

NOTE 3.51.10: Qt must be built as static lib in order for the
              AC_PATH_QT_WITHOUT_X macro to find it.

              For this version I have decided to build qt as;
              $ ./configure -static -thread

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

MySQL
-----

NOTE: If you want to use the sources from bk then you need to 
      execute the following in the mysql dir to create a 
      'configure' script;

      $ cp ../myodbc-3.51/Makefile.cvs .
      $ make -f Makefile.cvs macosx

      This will replace a few files for libtool so do not check
      any changes into bk when done.

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 --without-innodb
$ 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.

NOTE 3.51.10: configure option "--prefix=/usr" was added causing
              the files to be installed in /usr and not /usr/local.
 
MyODBC 3.51.10
--------------

This version of MyODBC build has greatly improved support for
OSX but you will still have a problem with a missing config.h
file for iODBC. The work around for this remains the same -
see MyODBC 3.51.9. 

The build now understands the difference between a 
regular share library and a bundle (plugin) and will build 
the driver and the setup library as bundles by default. 

Do the following to build/install MyODBC;
  
$ make -f Makefile.cvs macosx
$ ./configure --prefix=/usr --with-iODBC=/usr --with-iODBC-includes=/usr/include --with-ldflags=-lltdl --without-samples --disable-gui --disable-test
$ make
$ make install

This will result in the following files;

/usr/bin/myodbcinst            - driver installer
/usr/bin/imyodbc               - interactive SQL
/usr/lib/libmyodbc3.so         - driver (bundle)

We disabled the gui because there is, at this time, a
problem with libtool which causes the setup library
to be built with a few unresolved references. So we
use qmake to build the gui bits as follows;

$ qmake qmake.pro -o Makefile.qt
$ make -f Makefile.qt
$ make install

This will result in the following files;

/usr/lib/libmyodbc3S.dylib           - setup library (bundle)
srcdir/MYODBCConfig/MYODBCConfig.app - setup application

The qmake must be done after the gnu build because the gui
source uses the config include file generated by the gnu
build.

If the files build fine but fail to install you can cd to
the setup dir and do the following;

$ touch setup.pro
$ sudo make install

 
MyODBC 3.51.9
--------------

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 macosx".

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,
driver_r, and setup 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 you 
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;

NOTE 3.51.10: MYODBCConfig is now built and installed
              automatically when you build/install the
              driver. This will only happen if a viable
              Qt environment is found. Also; the setup
              library is a proper bundle with a "so" file
              extension now. 

$ 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.

NOTE: Just running "/Applications/Utilities/ODBC 
      Administrator" for the first time should create
      the need config files.

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

NOTE 3.51.10: myodbcinst is now built and installed
              automatically when you build/install the 
              driver.

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
2. use gui ODBC Administrator (does not show all
   driver options)
3. use "myodbcinst -e" to get a gui dialog (not good
   on OSX)
4. use MYODBCConfig to get gui dialog (recommended
   - and used during install)

imyodbc
-------

Now make imyodbc by doing the following;

$ cd imyodbc
$ make -f Makefile.osx

NOTE 3.51.10: imyodbc is now built and installed
              automatically when you build/install the 
              driver.

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

$ qmake
$ make

NOTE 3.51.10: You may have already built this if you have
              use the qmake project in the root souorce dir.

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 readme 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 -r /Applications/Utilities/MYODBCConfig.app
$ sudo rm -r ~/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 <pharvey@mysql.com                             |
+-------------------------------------------------------------+