Difference between revisions of "Mac OS X:Build from source:Application package"
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 | + | ==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 [https://www.gtk.org/ GTK]. | |
− | This is a command-line process. It's not too difficult, but you'll be using | + | 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. |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | If | + | 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. |
− | + | === 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 <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. | |
− | |||
− | + | 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. | |
− | |||
− | |||
− | |||
− | + | === Step 2: Install jhbuild === | |
− | |||
− | + | Next, read [https://wiki.gnome.org/Projects/GTK/OSX/Building the build instructions for Gtk-OSX], '''''especially the Prerequisites'''''. | |
− | + | ''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. | |
− | + | Then follow the steps under [https://wiki.gnome.org/Projects/GTK/OSX/Building#Procedure 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 <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>. | |
− | + | 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 | ||
− | ' | + | ==== .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. | ||
− | + | 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]). | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | === Webkit === | |
− | + | 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. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
== Bundling == | == Bundling == | ||
− | The next step is to create an application bundle. You'll need gtk-mac-bundler, so follow the instructions in the [ | + | 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 | + | 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 | ||
− | + | gtk-mac-bundler ~/gtk/src/gramps/mac/gramps.bundle | |
− | gtk-mac-bundler ~/gramps | ||
Line 84: | Line 60: | ||
== Packaging == | == Packaging == | ||
− | To make an uploadable disk image, create a folder named "Gramps | + | 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! | ||
− | + | [[Category:Developers/General]] | |
− | |||
− |
Revision as of 18:45, 2 June 2020
Contents
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!