Difference between revisions of "Mac OS X:Build from source:Application package"

From Gramps
Jump to: navigation, search
m (Building GRAMPS from Scratch: Sigh, I'll get it right eventually)
m (Building Gramps from Scratch: minor grammar)
(27 intermediate revisions by 5 users not shown)
Line 1: Line 1:
==Building GRAMPS from Scratch==
+
==Building Gramps from Scratch==
  
Building Gramps from scratch is useful to produce a version not currently available as a binary (for example, a PPC version) or to produce a complete environment for debugging and further development, including debugging of all the C libraries Gramps uses, like gtk.
+
Being able to building Gramps from scratch (from the fundamental Python scripts) is useful to produce a version not currently available as a binary for your particular OS platform or version. Or, to produce a complete environment for debugging and further development, including debugging of all the C libraries Gramps uses... like [https://www.gtk.org/ GTK].
  
This is a command-line process. It's not too difficult, but you'll be using Terminal.app, not XCode. Unfortunately, Gtk has so far resisted efforts to get it to successfully cross-compile PPC on Intel or vice-versa, so the whole process must be repeated on machines of each architecture. '''''WebKit will not build on 10.4 (Tiger) or earlier systems, nor will it build against a 10.4 SDK. You must be running 10.5 (Leopard) or newer for this procedure to succeed!'''''
+
This is a "[https://www.cybrary.it/blog/0p3n/command-line-interface-cli-vs-graphical-user-interface-gui/ command line interface]" process. It's not too difficult, but you'll be using [https://wikipedia.org/wiki/Terminal_(macOS) Terminal.app] and, not the [https://wikipedia.org/wiki/Xcode XCode] integrated development environment.  
 
You'll need XCode, Apple's development environment. There's a copy on your OS X distribution DVD, or you can download the latest version from [http://developer.apple.com/technologies/xcode.html Apple], though you must register as a Mac developer. For Lion users, XCode is available for free from the App Store.
 
 
 
Next, read [http://live.gnome.org/GTK%2B/OSX/Building the build instructions for Gtk-OSX], '''''especially the Prerequisites'''''. Download and run the [http://git.gnome.org/browse/gtk-osx/plain/gtk-osx-build-setup.sh gtk-osx-build-install.sh] script, which will set up jhbuild for you.
 
 
 
''It's important that jhbuild is not confused by any existing MacPorts or Fink installation.'' For this reason, it can be convenient to create a new Mac User account and log in to that account.
 
  
If you are building for distribution, you'll need to set up your build system to build for Leopard (OS X 10.5) and later. For those using Leopard or Snow Leopard, this is straightforward: Just set up for SDK 10.5 in .jhbuildrc-custom. With more recent OS X versions, you'll need to [https://live.gnome.org/GTK%2B/OSX/Building#Installing_XCode_3_on_XCode_4_systems use Xcode 3].
+
If you're not familiar with using the unix command line, you might find the frequent use of "~" ([https://www.dictionary.com/browse/tilde?s=t tilde]) below puzzling. It refers to the user's home directory (mine is /Users/john; if your name is John, then yours probably is too.) You can use it that way in commands if your current directory is somewhere else.
  
If you're not familiar with using the unix command line, you might find the frequent use of "~" below puzzling. It refers to the user's home directory (mine is /Users/john; if your name is John, then yours probably is too.) You can use it that way in commands if your current directory is somewhere else.
+
=== Step 1: Install Xcode ===
  
jhbuild is installed in ~/Source/jhbuild, and produces a binary which appears in ~/.local/bin. You'll want to add ~/.local/bin to your path:
+
You'll need a compiler. Apple provides two ways to install one: "Command Line Tools" installs just the command-line build environment and puts most of the header files in <tt>/usr/include</tt>. Simply trying to run a program that requires it like <tt>gcc</tt> or <tt>git</tt> should produce a dialog box offering to install them, but if that doesn't work you can run <tt>sudo xcode-select --install</tt>. Apple also has a full-featured integrated development environment called Xcode. It's available for free from the App Store.
  export PATH=~/.local/bin:$PATH
 
  
Next, you'll need to get a local copy of the gramps mac configuration stuff from svn (if you already have a gramps svn sandbox, then skip this step and substitute the path to it where appropriate below). This varies by version. For the current release branch at the time of this writing:
+
If you try to download Xcode, Apple will probably offer you the latest version of Xcode, irrespective of whether it runs on the version of Mac OS X you are using (Apple probably expects you to upgrade everything to the very latest). You may need to search for an earlier version. For example, if you're running Mac OS X 10.11 El Capitan, then it is probably best to use Xcode 7 (e.g. Xcode 7.3.1). Older versions of Xcode are available from [https://developer.apple.com/downloads Apple's developer site]; you'll need to register your AppleID for development.
    svn co https://gramps.svn.sourceforge.net/svnroot/gramps/branches/maintenance/3.4/mac gramps-mac
 
That will make a current copy from the repository in your current directory, which we'll assume to be ~.
 
  
The Gtk-OSX build instructions are very straightforward, but we need to deviate from them a bit to keep from doing things more than once. Run the following commands from the terminal:
 
  
  jhbuild bootstrap
+
=== Step 2: Install jhbuild ===
  jhbuild --moduleset=~/gramps-mac/gramps.modules build meta-gtk-osx-bootstrap berkeleydb python meta-gtk-osx-core meta-gtk-osx-python gramps
 
  
jhbuild by default puts everything it is building in ~/gtk (controlled by the hidden files ~/.jhbuildrc and ~/.jhbuildrc-custom ). ~/gtk/source contains the downloaded sources, and ~/gtk/inst contains the built libraries and applications. More is built than is needed in the final Gramps application - for example, the build tools are themselves built.
+
Next, read [https://wiki.gnome.org/Projects/GTK/OSX/Building the build instructions for Gtk-OSX], '''''especially the Prerequisites'''''.  
  
At this point, you can do
+
''It's important that jhbuild is not confused by any existing [https://wikipedia.org/wiki/Homebrew_(package_manager) Homebrew], [https://wikipedia.org/wiki/MacPorts MacPorts], or [https://wikipedia.org/wiki/Fink_(software) Fink] installation.'' For this reason, it can be convenient to create a new Mac User account and log in to that account if you have any of those installed.
  
  jhbuild shell
+
Then follow the steps under [https://wiki.gnome.org/Projects/GTK/OSX/Building#Procedure Procedure]
  gramps
 
  
at the command line and run gramps. Most everything will work (see the note about spelling dictionaries above).
+
=== Step 3: Install Gramps dependencies and Gramps ===
  
Once you've done this once, you can generally get away with just running
+
   curl -o gramps.modules https://raw.githubusercontent.com/gramps-project/gramps/maintenance/gramps50/mac/gramps.modules
   jhbuild --moduleset=~/gramps-mac/gramps.modules build meta-gtk-osx-bootstrap meta-gtk-osx-gtk3 berkeleydb python meta-gtk-osx-python-gtk3 gramps
+
or
to update everything that has been changed since the previous build. Most of the time nothing will have changed except gramps itself.
+
  curl -o gramps.modules https://raw.githubusercontent.com/gramps-project/gramps/master/mac/gramps.modules
  
If you want to build the svn trunk, you should use the trunk setup files:
+
  jhbuild --moduleset=~/gramps.modules build meta-gtk-osx-bootstrap gramps
    svn co https://gramps.svn.sourceforge.net/svnroot/gramps/trunk/mac gramps-mac-svn
 
and
 
  jhbuild --moduleset=~/gramps-mac/gramps.modules build meta-gtk-osx-bootstrap meta-gtk-osx-core berkeleydb4.8 python2.7 meta-gtk-osx-python gramps-svn
 
Should you want both installed, you'll need to set up separate prefixes in .jhbuildrc-custom; gramps doesn't version its installations, so the most recent will overwrite the previous build.
 
  
== Gramps 3.3 and EXIF Editing ==
+
If you want to build the latest release tarball rather than the latest check-in, use <tt>gramps</tt> instead of <tt>gramps-git</tt> for the last module--but note that since we don't release from the <tt>master</tt> branch, <tt>gramps.modules</tt> doesn't have a <tt>gramps</tt> module in <tt>master</tt>.
  
Gramps 3.3.0 introduced a new module, EXIF Editing, which has two tricky dependencies, which JHBuild doesn't know how to handle yet. In order to evade the persnickityness of jhbuild's dependencies, they're given as "soft" dependencies -- you have to add them to your modules list. If you don't, Gramps will still build fine, you'll just get a warning notice about Exiv2 not being installed.
+
If you're planning to work on several branches, a single checkout will work: Start with <tt>master</tt>. Gramps is pure python, so once you've got everything built you need repeat this only to update the dependencies. You can quickly switch branches in your git repo with:
 +
  git clean -fdx
 +
  git checkout maintenance/gramps40
 +
  python setup.by build
  
'''Warning:'''Boost-python will not successfully build with either the 10.6 (Snow Leopard) or 10.7 (Lion) SDKs. With 10.7 it won't build at all; with 10.6, it will build but will crash Python on import. Consequently you can't build EXIF editing using Lion, since earlier SDKs are not available.
+
==== .jhbuildrc-custom ====
 +
It's tedious and error-prone to type the long list of modules every time you want to build gramps. So you may want to modify <tt>~/.jhbuildrc-custom</tt> to declare the <tt>moduleset</tt> and <tt>modules</tt> variables. Note that <tt>.jhbuildrc-custom</tt> is a Python file that is loaded and executed by <tt>jhbuild</tt>, so you can make it quite complex.  
  
The first is [http://www.boost.org/libs/python/doc/ Boost-python], a python interface for C++ provided as part of [http://www.boost.org/ Boost]. It uses its own build system, bjam. Since jhbuild doesn't know how to use bjam, it will download the package for you, then error out. Select item 4, "start a shell", and do the following:
+
Do be aware that defining new global variables will elicit a warning from <tt>jhbuild</tt> so be careful to prefix any top-level variables with '_' ([https://www.dictionary.com/browse/underscore?s=t underscore]).
  cd tools/build/v2
 
  ./bootstrap.sh --with-toolset=darwin
 
  ./bjam --prefix="$PREFIX" install
 
  cd ../../..
 
  bjam toolset=darwin address-model=32 --prefix=$PREFIX --with-python --cmd-or-prefix=$PYTHON cxxflags="$CXXFLAGS" cflags="$CFLAGS" linkflags="$LDFLAGS" install
 
  
Once that's done, quit the shell and select "2" (ignore error) twice to move on to the next library, [http://tilloy.net/dev/pyexiv2/ PyExiv2], which also uses a different build system, [http://www.scons.org/ SCons]. The SCons folks are bright enough to use distutils, which JHBuild ''can'' handle, so that gets built and installed for you. JHBuild will stop again after downloading and extracting PyExiv for you, so once again select "4" to start a shell and run the following:
+
=== Webkit ===
  export CXXFLAGS="$CXXFLAGS -I$PREFIX/include"
+
Gramps has an optional dependency on [https://webkit.org/ WebKit], which is used for the <tt>html-renderer</tt> add-on. If for some reason you want to use this add-on, add <tt>WebKit</tt> to your list of dependencies but be aware that it may take a long time to build.
  export CFLAGS="$CFLAGS -I$PREFIX/include"
 
  export LDFLAGS="$LDFLAGS -lpython2.7"
 
  scons
 
  scons install
 
  ln $PREFIX/lib/python2.7/site-packages/libexiv2python.dylib $PREFIX/lib/python2.7/site-packages/libexiv2python.so
 
  install_name_tool -id python2.7/site-packages/libexiv2python.dylib $PREFIX/lib/python2.7/site-packages/libexiv2python.dylib
 
Quit the shell and pick "2" a few more times to move on to the next module.
 
  
 
== Bundling ==
 
== Bundling ==
The next step is to create an application bundle. You'll need gtk-mac-bundler, so follow the instructions in the [http://live.gnome.org/GTK%2B/OSX/Bundling Gtk-OSX Wiki] to download and install it.
+
The next step is to create an application bundle. You'll need gtk-mac-bundler, so follow the instructions in the [https://wiki.gnome.org/Projects/GTK/OSX/Bundling Gtk-OSX Wiki] to download and install it.
  
You may need to edit <tt>~/gramps-mac/Info.plist</tt> to update the version number and copyright information.
+
Assuming that your local repository wound up in <tt>~/gtk/src/gramps</tt>:
 +
You may need to edit <tt>~/gtk/src/gramps/mac/Info.plist</tt> to update the version number and copyright information.
  
 
Now open a jhbuild shell and run the bundler:
 
Now open a jhbuild shell and run the bundler:
 
   jhbuild shell
 
   jhbuild shell
  chmod +w $PREFIX/lib/libpython2.6.dylib
+
   gtk-mac-bundler ~/gtk/src/gramps/mac/gramps.bundle
   gtk-mac-bundler ~/gramps-mac/gramps.bundle
 
 
   
 
   
  
Line 84: Line 60:
 
== Packaging ==
 
== Packaging ==
  
To make an uploadable disk image, create a folder named "Gramps-arch-version", replacing "arch" with either Intel or PPC and "version" with the current version number. Drag your app bundle to this directory. Open your build directory and copy (option-drag) the files "FAQ", "COPYING", "README", and "NEWS" to the Gramps folder you just made. Rename each to have a ".txt" extension so that they're readable with QuickLook. You might also rename COPYING to License.txt so that it's meaning is more clear to users who aren't familiar with the GPL.
+
To make an uploadable disk image, create a folder named "Gramps-version", replacing "version" with the current version number. Drag your app bundle to this directory. Open your build directory and copy (option-drag) the files "FAQ", "COPYING", "README", and "NEWS" to the Gramps folder you just made. Rename each to have a ".txt" extension so that they're readable with QuickLook. You might also rename COPYING to License.txt so that its meaning is more clear to users who aren't familiar with the GPL.
  
 
Now open Applications>Utilities>Disk Utility and select File>New Image From Folder and select your folder, then approve the name and location. You'll have a dmg ready for distribution.
 
Now open Applications>Utilities>Disk Utility and select File>New Image From Folder and select your folder, then approve the name and location. You'll have a dmg ready for distribution.
Line 90: Line 66:
 
Good Luck!
 
Good Luck!
  
'''Note:''' The 3.1.2 installer left out two files:
+
[[Category:Developers/General]]
#''_strptime.py''. You can get the file from  [http://www.gramps-project.org/bugs/view.php?id=3177 here].
 
#''keysyms.py''. You can get the file from  [http://www.gramps-project.org/bugs/view.php?id=3157 here].
 

Revision as of 18:45, 2 June 2020

Building Gramps from Scratch

Being able to building Gramps from scratch (from the fundamental Python scripts) is useful to produce a version not currently available as a binary for your particular OS platform or version. Or, to produce a complete environment for debugging and further development, including debugging of all the C libraries Gramps uses... like GTK.

This is a "command line interface" process. It's not too difficult, but you'll be using Terminal.app and, not the XCode integrated development environment.

If you're not familiar with using the unix command line, you might find the frequent use of "~" (tilde) below puzzling. It refers to the user's home directory (mine is /Users/john; if your name is John, then yours probably is too.) You can use it that way in commands if your current directory is somewhere else.

Step 1: Install Xcode

You'll need a compiler. Apple provides two ways to install one: "Command Line Tools" installs just the command-line build environment and puts most of the header files in /usr/include. Simply trying to run a program that requires it like gcc or git should produce a dialog box offering to install them, but if that doesn't work you can run sudo xcode-select --install. Apple also has a full-featured integrated development environment called Xcode. It's available for free from the App Store.

If you try to download Xcode, Apple will probably offer you the latest version of Xcode, irrespective of whether it runs on the version of Mac OS X you are using (Apple probably expects you to upgrade everything to the very latest). You may need to search for an earlier version. For example, if you're running Mac OS X 10.11 El Capitan, then it is probably best to use Xcode 7 (e.g. Xcode 7.3.1). Older versions of Xcode are available from Apple's developer site; you'll need to register your AppleID for development.


Step 2: Install jhbuild

Next, read the build instructions for Gtk-OSX, especially the Prerequisites.

It's important that jhbuild is not confused by any existing Homebrew, MacPorts, or Fink installation. For this reason, it can be convenient to create a new Mac User account and log in to that account if you have any of those installed.

Then follow the steps under Procedure

Step 3: Install Gramps dependencies and Gramps

 curl -o gramps.modules https://raw.githubusercontent.com/gramps-project/gramps/maintenance/gramps50/mac/gramps.modules

or

 curl -o gramps.modules https://raw.githubusercontent.com/gramps-project/gramps/master/mac/gramps.modules
 jhbuild --moduleset=~/gramps.modules build meta-gtk-osx-bootstrap gramps

If you want to build the latest release tarball rather than the latest check-in, use gramps instead of gramps-git for the last module--but note that since we don't release from the master branch, gramps.modules doesn't have a gramps module in master.

If you're planning to work on several branches, a single checkout will work: Start with master. Gramps is pure python, so once you've got everything built you need repeat this only to update the dependencies. You can quickly switch branches in your git repo with:

 git clean -fdx
 git checkout maintenance/gramps40
 python setup.by build

.jhbuildrc-custom

It's tedious and error-prone to type the long list of modules every time you want to build gramps. So you may want to modify ~/.jhbuildrc-custom to declare the moduleset and modules variables. Note that .jhbuildrc-custom is a Python file that is loaded and executed by jhbuild, so you can make it quite complex.

Do be aware that defining new global variables will elicit a warning from jhbuild so be careful to prefix any top-level variables with '_' (underscore).

Webkit

Gramps has an optional dependency on WebKit, which is used for the html-renderer add-on. If for some reason you want to use this add-on, add WebKit to your list of dependencies but be aware that it may take a long time to build.

Bundling

The next step is to create an application bundle. You'll need gtk-mac-bundler, so follow the instructions in the Gtk-OSX Wiki to download and install it.

Assuming that your local repository wound up in ~/gtk/src/gramps: You may need to edit ~/gtk/src/gramps/mac/Info.plist to update the version number and copyright information.

Now open a jhbuild shell and run the bundler:

 jhbuild shell
 gtk-mac-bundler ~/gtk/src/gramps/mac/gramps.bundle

You'll have an application bundle named Gramps.app on your desktop.

Packaging

To make an uploadable disk image, create a folder named "Gramps-version", replacing "version" with the current version number. Drag your app bundle to this directory. Open your build directory and copy (option-drag) the files "FAQ", "COPYING", "README", and "NEWS" to the Gramps folder you just made. Rename each to have a ".txt" extension so that they're readable with QuickLook. You might also rename COPYING to License.txt so that its meaning is more clear to users who aren't familiar with the GPL.

Now open Applications>Utilities>Disk Utility and select File>New Image From Folder and select your folder, then approve the name and location. You'll have a dmg ready for distribution.

Good Luck!