GrampsAIO-4 package updating

From Gramps
Revision as of 06:07, 26 March 2016 by Sam888 (talk | contribs) (Add Draft 7 from Paul Franklin. - before reformatting for wiki)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Please wait until I 've formatted this abit

The Gramps "software bundle" for Windows or GrampsAIO is an all-in-one (a.k.a. "AIO") installation package of Gramps which includes all dependencies for the Windows platform.


This tutorial describes how to generate an upgraded Windows AIO package from an older Windows AIO package -- how to take one with an older gramps and make one with a newer gramps.

It is intended for Windows users and does not attempt to describe how to do the same thing on linux or a Mac.

("AIO" means all-in-one, which means that everything you need to run gramps is included in the one AIO file you download and then install -- all the related programs and library files which gramps needs on Windows.)

Note that the first gramps AIO package was created by an advanced Windows power-user named Josip. He is the one who evolved the AIO package and modified the AIO package over the years as gramps has changed. Everything documented here was done by him (which includes compiling all the related programs and libraries, their files and folders). Any gramps Windows user owes him a large debt of gratitude.

Note also that in this tutorial I am only changing an "old" gramps (4.2.1 in this tutorial) into a "new" gramps (4.2.2 in this tutorial). This tutorial does not attempt to tell how to update any other program in the Windows AIO package (for instance Graphviz or Python or Gtk3). All of those programs (and their related "library" files) are unchanged at the end of the this tutorial's process. (Any "upstream" bug in the 4.2.1 AIO will still be there in the 4.2.2 AIO.)

Also, this tutorial has a mixture of methods which may be used, sometimes explaining via the Windows Explorer (a GUI method) and sometimes explaining via the Windows command shell ("DOS window" -- a CLI method). There is only one place in this tutorial which can only be done one way (running the Python command) so feel free to do everything else by whatever method you prefer.

Installing the old gramps

To start following this tutorial you will need an installed gramps made from an AIO.

I believe that gramps needs to have been installed in an NTFS partition (to preserve case-sensitive file names).

So we will first download a gramps AIO.

(It might be possible to follow these instructions using an older gramps as the starting point but I have not done that and do not know if it will work, therefore I am not further commenting on that possibility.)

I advise that you start with the previous released Windows version of gramps, so in this tutorial I will start with a "4.2.1" AIO gramps and make a "4.2.2" AIO gramps. If you want to do something different, change the numbers and filenames accordingly.

(A similar method should work if you want to experiment by running the currently-unreleased next major version of gramps on Windows. (Currently, the "master" branch of gramps will eventually be released as gramps "5.0.0".) I will not describe how to do that, downloading it and so forth, as only "power users" should attempt it and the information in this tutorial should be enough to tell anybody like that what to do.)

So start by downloading the 4.2.1 AIO of gramps.

It should match the Windows operating system you have installed. That is, if you have a 32-bit Windows 7 or Windows 10, download the 32-bit AIO:

If you have a 64-bit Windows, download the 64-bit AIO:

When you start the installer, it will ask you a few things and then ask where you want it installed. You can install it where you want, as it is only a temporary location which will be deleted afterward. But make a note of the folder since you will need to know it later. Also, it needs to be a new (empty) folder, not an already existing one.

In this tutorial we'll say you tell the installer to put it into a new "C:\tempAAA" folder.

Then double-click on the AIO executable to start the 4.2.1 installation. (If your Windows asks whether you will allow that program to change things on your computer, say yes of course.)

You can put it anywhere you want but many things which happen are based on "relative" folder locations, so the folder structure cannot be altered (unless you really know what you are doing and modify lots of things accordingly). So you can change the string "tempAAA" in this tutorial to the actual name you used. But every time I use "tempAAA" I mean the top of the tree where you installed the "old" AIO.

After the installer is finished, the last window will offer you the opportunity to "Run" the gramps you just installed, so you should un-click that box before you hit "Finish", since there is no need to run the old one.

Similarly, you can delete the "GrampsAIO32 4.2.1" icon shortcut from your Desktop, since you won't be using it.

Modifying the old gramps AIO

Now start a command-prompt window (Start=>Accessories) with executive power (right-click and "Run as administrator").

I am using gramps 4.2.1 in this tutorial, as the gramps AIO I am upgrading from. If you are using a later AIO version you can perhaps skip the next step. But if you have installed the 4.2.1 AIO package there is an additional step you have to take: a file is missing in the 4.2.1 AIO package so you need to install it.

If you will be making a 32-bit AIO on a 32-bit Windows machine then download the 32-bit version of the file from:

If you will be making a 64-bit AIO, download the file from:

Now make the folder it will go into:

 mkdir C:\tempAAA\include\python3.5m

Then move the newly-downloaded pyconfig.h file into that newly-created folder. (So it will end up as the C:\tempAAA\include\python3.5m\pyconfig.h file.) Remember, those steps will only be required if you are starting with a 4.2.1 (or earlier) AIO.

Now delete some old gramps files (or use Explorer to do it):

 rmdir /s /q C:\tempAAA\share\gramps
 rmdir /s /q C:\tempAAA\share\doc\gramps
 rmdir /s /q C:\tempAAA\lib\python3.5\site-packages\gramps

(The 4.2.1 gramps AIO has Python version 3.5 in it, so if you are starting from a different AIO you may need to modify that last line slightly.)

(There are other gramps files which were created when you installed the old AIO gramps but we will not delete them, since they will be overwritten by the same filenames from a newer gramps version, for instance the translation files, or else remain the same, such as icons.)

Installing the new gramps tree

Now download the source file for the gramps which you want to make an AIO package of, 4.2.2 in this example:

That (gramps-4.2.2.tar.gz) file is a "compressed" file and you will need a program which can decompress it. There are many programs which do that so I leave the choice up to you. (If your program asks you whether you want the "tar" archive decompressed also, say yes.)

You can put it almost any place you want since it is only temporary and you will remove it when you are done.

But that folder can't be anywhere inside the C:\tempAAA tree. You must pick a location outside the C:\tempAAA tree.

In this tutorial I will decompress it into C:\temp422.

When you decompress it, you will end up with a "gramps-4.2.2" folder inside whatever top-level folder you asked for, let's say in C:\temp422, so you can make things easier to type by saying:

 set g422=C:\temp422\gramps-4.2.2

I am using gramps 4.2.2 in this tutorial, as the gramps I am upgrading to. If you are using a later gramps version you can probably skip the next step. But if you are generating a 4.2.2 AIO package there is an additional step you have to take. The file po/el.po in the gramps 4.2.2 tar.gz archive file is defective and must be replaced. So download its replacement from:

Then replace the po\el.po in C:\temp422\gramps-4.2.2 with the newly-downloaded el.po file.

Since you need to run some of the programs which were installed as part of the old gramps, prepend the folder they are in to the start of your path (the list of folders where Windows will search for programs). The separator is a semicolon:

 set path=C:\tempAAA\bin;%path%

(If you are already in C:\tempAAA\bin you can say

 set path=%cd%;%path%


Once you have updated the el.po file (if you are upgrading to 4.2.2), go to the decompressed 4.2.2 directory, if you are not there already. (But if it is on a different disk you will have to type the disk letter also):

 cd %g422%

then say:

 python install --prefix=C:\tempAAA > C:\temp422\install-log.txt

where the "prefix" argument is the folder name where you installed the old 4.2.1 gramps AIO, C:\tempAAA in this tutorial.

Any errors should be typed on your command-shell screen. (At least they were for me, for instance complaints about the po\el.po file before I replaced it.)

If there were no errors, you can read the install-log.txt file if you want. They are the log message of what the "install" command did, the command you just ran. You might make sure everything went fine by reading its end lines.

(If you want to, you can split the "install" into its two parts -- the "build" and then the "install" -- by first running "python build" before you run the "install" line I showed earlier, but the "install" command has to have the "prefix" argument, as I showed.)

Packaging the new gramps AIO

Now that the folders containing the new 4.2.2 gramps have been made, we need to "package" it into an AIO Windows executable, a so-called "installer".

Any GrampsAIO package is made by using NSIS, the Nullsoft Scriptable Install System, an open-source packaging system.

Its homepage is and you should download the newest version (currently 3.0b3) and not the earlier version (currently 2.50).

But when you install it, don't accept its suggested installation folder if that folder path has a space in it, since (in nsis-3.0b3 or nsis-2.50) there is a bug and it cannot cope with such a path (when running in CLI mode, to my amazement). Instead, modify the suggested folder name to have no space in it -- so I changed C:\Program Files\NSIS to C:\NSIS instead. (You can uninstall NSIS when you're done.)

(Since I didn't know what was needed, I left the suggested type of installation at "Full".)

Upon installation, it popped up a nice window showing the NSIS Users Manual. (More information than you want to know, probably.)

The NSIS script file which controls how the gramps AIO package is made is called src\gramps.nsi and that folder is located in the same "top" folder we installed the old AIO into -- C:\tempAAA -- so first make a copy of the original gramps.nsi just in case, for instance onto your Desktop.

(The gramps.nsi file is written for NSIS3, for instance the line which has "x86-ansi" as a subfolder of NSIS\Plugins; that "x86-ansi" subfolder is only in the NSIS3 version.)

Then open the C:\tempAAA\src\gramps.nsi file with your favorite editor.

(One user reported unicode problems with Notepad and then downloaded Notepad++ -- I used Wordpad, as I recall.)

Change the APPVERSION line from "4.2.1" to "4.2.2" instead.

Possibly APPNAME and APPBUILD will need changing too, depending on what you are trying to do, but I didn't have to, to make a 4.2.2 from the 4.2.1 AIO -- since the 4.2.1 APPBUILD already had "1" in it and the same thing would be needed for the 4.2.2 gramps.

(If you are a power user and have downloaded something other than a tar.gz file, see Appendix A to change APPBUILD.)

If necessary, change the BrandText line to have the name of the new gramps release instead of the old release name. (The top of the C:\tempAAA\share\doc\gramps\NEWS file will show any new release name, but 4.2.2 doesn't seem to have any special name, so I didn't have to change that line.)

If necessary, edit the APP_PUBLISHER line to say "The Gramps project" instead of "The GRAMPS project".

Normally, that would be all that is needed. But if you are making a 4.2.2 from 4.2.1 as in this tutorial, you might remember that earlier we added a top-level "include" folder (and its contents). So we need to modify the 4.2.1 gramps.nsi file (which will become the new 4.2.2 gramps.nsi file) to have that change.

So search for the string "\etc" and notice it is on two lines about halfway down. Copy those two lines to two new lines just below them. Then change the "etc" string in the two new lines to say "include" instead. That is, after:

 File /r "..\etc\"

add these two additional lines:

 SetOutPath "$INSTDIR\include\"
 File /r "..\include\"

Then save that gramps.nsi file, write it out.

If you are not already in that "src" folder, go there:

 cd C:\tempAAA\src

(The NSIS script needs to be run while in that directory.)

Then you will run the NSIS compiler on the file you just edited. But for some unknown reason, I was not able to say just "makensis gramps.nsi" in the shell window, although the documentation said it should work.

So there are two other possibilities. (I did it both ways (GUI and CLI) and both worked for me.)

One way is to open that C:\tempAAA\src folder in an Explorer window and then right-click on the gramps.nsi file to choose "Compile NSIS Script" from the choices.

The other way is to type the full pathname to the compiler, which in my case was:

 C:\NSIS\makensis gramps.nsi

Note that after the compilation, the resulting files will be compressed and that compression probably will take a while -- OVER FIVE MINUTES FOR ME -- so be patient. (See Appendix B for power-user details, at this stage.)


Assuming the compilation and compression were successful, move the resulting file out of the C:\tempAAA\src folder:

 move C:\tempAAA\src\GrampsAIO-4.2.2-1_win32.exe ..\..

You now no longer need C:\tempAAA and it may be deleted, but remember that the "old" gramps was "installed" into it, so first tell Windows to uninstall it (4.2.1 in this tutorial).

Similarly, the gramps-4.2.2 tree may be deleted (%g422%).

Appendix A

If you are a power user, you might have downloaded the latest code in the gramps42 branch (which will become 4.2.3 eventually, as I write this tutorial):

but in any case, if you have downloaded something other than a tar.gz file, say this in your top directory (%g422%):

 git rev-list --count HEAD

and then

 git rev-parse --short HEAD

and then put an "r" in front of the first string, followed my a hyphen ("-") and the second string, and then use the resulting combined string as your APPBUILD, for clarity.

So for example your APPBUILD line might look like this:

 !define APPBUILD "r23381-25018d6"

If you are a developer and plan to upload it to SourceForge and it is an AIO of (a forthcoming) "master" put it into:

but if it is an AIO for a maintenance branch, make a Snapshots folder in that branch and put it there, e.g.:

so then the APPBUILD numbers will uniquely define that AIO.

But note that the NSIS-generated filename will say (for instance) "4.2.3" even though it is really a "4.2.2" with bugs fixed, which is why it belongs in 4.2.2/Snapshots.

Appendix B

If you are a power user and are experimenting with slight changes to the gramps.nsi script, you can drastically shorten the time needed to have NSIS generate an AIO package by commenting out these two lines (with a semicolon, a ";"):

 SetCompressor /SOLID /FINAL LZMA
 SetCompressorDictSize 128

But if you are building an AIO which will be released to the public (put onto the official gramps files repo), you need to be /very sure/ to uncomment /both/ those lines /first/.

See also