Difference between revisions of "CMake:MacOSX Frameworks"

From KitwarePublic
Jump to navigationJump to search
(Remove leading space rectangles from preformatted blocks)
(Replace content with link to new CMake community wiki)
 
Line 1: Line 1:
This page has been broken out from [[CMake:Bundles_And_Frameworks]] so as to better concentrate soley on Mac OS X Framework bundles.
{{CMake/Template/Moved}}


==What is a Framework?==
This page has moved [https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/platform_dependent_issues/MacOSX-Frameworks here].
Frameworks are shared libraries that are packaged with associated resources, such as graphics files, developer documentation, and programming interfaces. See [http://developer.apple.com/documentation/DeveloperTools/Conceptual/MachOTopics/Articles/loading_code.html#//apple_ref/doc/uid/TP40001830-96836 "Using Shared Libraries and Frameworks"] in [http://developer.apple.com/documentation/DeveloperTools/Conceptual/MachOTopics/Articles/loading_code.html#//apple_ref/doc/uid/TP40001830-SW1 “Loading Code at Runtime”] for more information. [http://developer.apple.com/documentation/DeveloperTools/Conceptual/MachOTopics/Articles/building_files.html#//apple_ref/doc/uid/TP40001828-97030-TPXREF106]
 
See also:
* [http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html Framework Programming Guide]
* [http://developer.apple.com/documentation/DeveloperTools/Conceptual/DynamicLibraries/Articles/DynamicLibraryDesignGuidelines.html Dynamic Library Design Guidelines]
 
==Issues==
* ADD_LIBRARY as it exists now does not provide enough functionality.
* CMAKE_INSTALL_PREFIX is not enough. When creating frameworks, auxilary files (i.e. header files and resources) should be in the proper subdirectory structure.
 
==Current Status==
* Linking to frameworks works.
* Creating frameworks is just being started. (The plan is to document the design and implementation on this wiki page.)
* 24/Oct/2006 - I have very, very preliminary support for creating frameworks with CMake at [http://wtl.wayfarer.org/cmake/ http://wtl.wayfarer.org/cmake/].  '''Note that this is in no way ready to be merged and probably won't even work for you!'''  But, it does create a framework bundle for me.  Unfortunately, even though the bundle will link, it won't run as the full path to the framework library isn't set correctly.  It's set as TARGET_INSTALLNAME_DIRframeworkname.  It also doesn't support header files in the framework yet.  It is just meant to be a starting place from which to move forward.  To ask questions about it or comment on it, please e-mail me (Tanner Lovelace) at clubjuggler at gmail dot com.
 
 
==Milestones==
* Shared library bundled as a framework
** Should just be a case of setting up the bundle correctly, outputting the shared library (using framework flags) and copying in the info.plist file.
** ''Should consider install_name issues.  I wonder if we can default to @executable_name/... as if it were an embedded framework and then have it work if it's placed in a standard framework location?''
* Framework versioning working
* Public header files copied into framework
* Specified resource files copied into framework
** ''Can we support umbrella frameworks as a special case of resource files?''
 
==Notation==
* In all examples, the applications are named appl1, appl2, ...
* libraries are named libr1, libr2, ...
* header files are named appl1_header1, appl2_header2, libr1_header1, ...
* there are auxilary files associated with application and library appl1_aux1, appl2_aux2, libr1_aux1, ...
* and some resource files associated with application and library appl1_res1, appl2_res2, libr1_res1, ...
* All versions are ver1, ver2, ...
* All libraries have lib in their name, while frameworks do not. To differentiate, all frameworks will have names FRlibr1, FRlibr2, ...
 
==Cases==
===Framework only===
* Everything in a same directory:
<pre>
/Library/
  Frameworks/
    FRlibr1.framework/
      FRlibr1  -> Versions/Current/FRlibr1
      Resources -> Versions/Current/Resources
      Libraries -> Versions/Current/Libraries
      Headers  -> Versions/Current/Headers
      Versions/
        Current -> ver2
        ver2/
          FRlibr1
          Resources/
          Info.plist
          version.plist
          Libraries/
            libr2.dylib
            libr3.dylib
          Headers/
            FRlibr1_header1.h
            FRlibr1_header2.h
            FRlibr1_header3.h
</pre>
 
* Suggested api:
<pre>
ADD_LIBRARY(
  FRlibr1
  SHARED MACOSX_FRAMEWORK
  appl1_src1.cxx
  appl1_src2.cxx
  FRlibr1_header4.h
  FRlibr1_header5.h
  FRlibr1_header6.h
  ...
  MACOSX_FRAMEWORK_PUBLIC_HEADERS
  FRlibr1_header1.h
  FRlibr1_header2.h
  FRlibr1_header3.h
  )
 
SET_TARGET_PROPERTIES(FRlibr1
  PROPERTIES
  VERSION ver2
  )
 
TARGET_LINL_LIBRARIES(
  FRlibr1
  libr2 libr3)
</pre>
 
Comment: (submitted by Tanner Lovelace) We need to have both the means of versioning frameworks and creating frameworks that aren't versioned.  If a framework doesn't have a version, it should be placed at the top level of the framework directory structure (or, alternatively, we could decide that all frameworks must have a version and either silently default to something like "A" (not recommended!) or cause an error).  If it does have a version, then it should be placed in the appropriate version directory and symlinks created to point to it.  The version may be any arbitrary string.  Apple itself generally uses capital letters (A, B, C, etc...) but the major version works just as well.  I believe it is suggested that anything below major version number not be used since libraries should be compatible within major version numbers.
 
==Linking Issues==
 
===Link a Framework===
 
Assuming:
<pre>
/usr/
  lib/
    libr3.dylib
/Library/
  Frameworks/
    FRlibr1.framework/   
      FRlibr1  -> Versions/Current/FRlibr1
      Resources -> Versions/Current/Resources
      Libraries -> Versions/Current/Libraries
      Headers  -> Versions/Current/Headers
      Versions/
        Current -> ver2
        ver2/
          FRlibr1
          Resources/
          Libraries/
            libr2.dylib
          Headers/
</pre>
 
Regular library is linked like this:
 
<pre>
libtool -dynamic libr3_src1.o libr3_src2.o -o libr3.dylib
</pre>
 
Framework is linked like this:
 
<pre>
mkdir -p FRlibr1.framework/Versions/ver2
gcc -dynamiclib -o FRlibr1.framework/Versions/ver2/FRlibr1 FRlibr1_src1.o FRlibr1_src2.o
cd ./FRlibr1.framework/Versions && ln -sf ver2 Current
cd ./FRlibr1.framework && ln -sf Versions/Current/FRlibr1 FRlibr1
</pre>
 
You link libr2.dylib like this:
 
<pre>
libtool -dynamic libr1_src1.o libr1_src2.o -o FRlibr1.framework/Versions/ver2/Libraries/libr2.dylib
</pre>
 
* Looks like the difference between linking framework and linking shared library is:
** Framework:
<pre>
gcc <b>-dynamiclib</b> -o FRlibr1.framework/Versions/ver2/FRlibr1 <sources>
</pre>
** Shard library:
<pre>
gcc <b>-dynamic</b> -o libr2 <sources>
</pre>
 
===Embedded Frameworks===
Assuming:
 
<pre>
/Applications/
  appl1.app/
    Contents/
      Info.plist
      MacOS/
        appl1 -> appl1-1
        appl1-1
      Resources/
      Framework/
        FRlibr1.framework/   
          FRlibr1  -> Versions/Current/FRlibr1
          Resources -> Versions/Current/Resources
          Versions/
            Current -> ver2
            ver2/
              FRlibr1
              Resources/
</pre>
 
You have to run: '''Add command here to create embedded framework'''
 
==Useful Tools==
(From http://developer.apple.com/documentation/DeveloperTools/Conceptual/MachOTopics/index.html)
 
Tools for analyzing Mach-O files include the following:
* The <i>/usr/bin/lipo</i> tool allows you to create and analyze binaries that contain images for more than one architecture. An example of such a binary is a universal binary. Universal binaries can be used in PowerPC-based and Intel-based Macintosh computers. Another example is a PPC/PPC64 binary, which can be used in 32-bit PowerPC–based and 64-bit PowerPC–based Macintosh computers.
* The file-type displaying tool, <i>/usr/bin/file</i>, shows the type of a file. For multi-architecture files, it shows the type of each of the images that make up the archive.
* The object-file displaying tool, <i>/usr/bin/otool</i>, lists the contents of specific sections and segments within a Mach-O file. It includes symbolic disassemblers for each supported architecture and it knows how to format the contents of many common section types.
* The page-analysis tool, <i>/usr/bin/pagestuff</i>, displays information on each logical page that compose the image, including the names of the sections and symbols contained in each page. This tool doesn’t work on binaries containing images for more than one architecture.
* The symbol table display tool, <i>/usr/bin/nm</i>, allows you to view the contents of an object file’s symbol table.
 
==Related Work==
 
* On mailing list: http://public.kitware.com/pipermail/cmake/2005-December/007725.html
* From apple:
** http://developer.apple.com/documentation/DeveloperTools/Conceptual/MachOTopics/index.html
** http://developer.apple.com/documentation/DeveloperTools/Conceptual/MachOTopics/Articles/loading_code.html#//apple_ref/doc/uid/TP40001830
** http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/index.html
** http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html
* From Trolltech: http://doc.trolltech.com/qq/qq09-mac-deployment.html
* Here is a good tutorial (via Quicktime movie) on how to create Embedded frameworks: http://rentzsch.com/cocoa/embeddedFrameworks
* [http://www.mac-how.net/ How to uninstall software on mac]
 
{{CMake/Template/Footer}}

Latest revision as of 15:40, 30 April 2018


The CMake community Wiki has moved to the Kitware GitLab Instance.

This page has moved here.