GrampsAIO-4 package updating
These instructions are obsolete as of Gramps 4.2.5. Instead use |
Gramps 4.2.0 to 4.2.4. Any comments and help (e.g. on wiki pages) are welcome. |
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.)
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.
NTFS partition I believe that Gramps needs to have been installed in an NTFS partition (to preserve case-sensitive file names). |
Download the old Gramps
So we will first download a Gramps AIO.
It's advisable 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.
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:
https://sourceforge.net/projects/gramps/files/Stable/4.2.1/GrampsAIO-4.2.1-1_win32.exe/download
If you have a 64-bit Windows, download the 64-bit AIO:
https://sourceforge.net/projects/gramps/files/Stable/4.2.1/GrampsAIO-4.2.1-2_win64.exe/download
Power users building 32-bit or 64-bit versions Note that both AIO versions can be built on 64-bit Windows. |
Install the old Gramps
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" (or GrampsAIO64 one)" icon shortcut from your Desktop, since you won't be using it.
Modifying the old Gramps AIO
Now start a command-prompt window (Start=>All Programs>Accessories>Command Prompt) 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 required add pyconfig.h
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:
https://github.com/gramps-project/gramps/raw/master/windows/AIO/32-bit/pyconfig.h
If you will be making a 64-bit AIO, download the file from:
https://github.com/gramps-project/gramps/raw/master/windows/AIO/64-bit/pyconfig.h
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.
Delete old Gramps files
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
del C:\tempAAA\lib\python3.5\site-packages\gramps-*.egg-info
Installing the new Gramps tree
Download Gramps source file
Now download the source file for the Gramps which you want to make an AIO package of, 4.2.2 in this example:
https://sourceforge.net/projects/gramps/files/Stable/4.2.2/gramps-4.2.2.tar.gz/download
Decompress/Extract the Gramps source file
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 you need a suggestion use 7-zip ( http://www.7-zip.org/ ) (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
If needed replace po/el.po
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:
https://github.com/gramps-project/gramps/blob/maintenance/gramps42/po/el.po?raw=true
Then replace the po\el.po in C:\temp422\gramps-4.2.2 with the newly-downloaded el.po file.
Prepend folder paths
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 |
Install the updated Gramps source
Go to the decompressed 4.2.2 directory C:\temp422\gramps-4.2.2
, 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 setup.py 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.
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".
Download and install NSIS
Any GrampsAIO package is made by using NSIS, the Nullsoft Scriptable Install System, an open-source packaging system. https://en.wikipedia.org/wiki/Nullsoft_Scriptable_Install_System
Its download page is https://nsis.sourceforge.io/Download and you should download the newest version (currently 3.0.4) and not the earlier version (currently 2.51).
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.0 or nsis-2.51) 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. (Since I didn't know what was needed, I left the suggested type of installation at "Full". You can uninstall NSIS when you're done.)
Upon installation, it popped up a nice window showing the NSIS Users Manual. (More information than you want to know, probably.)
Modifying the gramps.nsi script
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.
Only NSIS3 will work 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.
Part of the contents should look something like the following:
!define APPNAME "GrampsAIO32" !define APPVERSION "4.2.1" !define APPBUILD "1" !define APPNAMEANDVERSION "${APPNAME} ${APPVERSION}" !define APP_PUBLISHER "The GRAMPS project" !define APP_WEB_SITE "http://gramps-project.org" BrandingText "Version ${APPVERSION} -- a new maintenance release"
Make sure your editor works One user reported unicode problems with Notepad and then downloaded Notepad++ -- I used Wordpad, as I recall. |
Increase the version number
Change the APPVERSION line from "4.2.1" to "4.2.2" instead (or higher if making a newer version).
If needed update APPNAME and APPBUILD
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" (meaning it was the first build of that version) in it and the same thing would be needed for the 4.2.2 Gramps (although the 64-bit APPBUILD did need to be changed from a "2" to a "1" since it was the initial 4.2.2 64-bit release).
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 BrandingText line to have the name of the new Gramps release instead of the old release name.
Release names 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".
If required include the pyconfig.h
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\"
Save the file
Then save that gramps.nsi file, write it out.
Make the NSIS package
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.
Please be patient The NSIS package compression will probably take a while |
Experimenting with NSIS compression See Appendix B for power-user details, at this stage. |
Conclusion
Assuming the compilation and compression were successful, move the resulting file out of the C:\tempAAA\src
folder:
For the 32 bit version:
move C:\tempAAA\src\GrampsAIO-4.2.2-1_win32.exe ..\..
For the 64 bit version:
move C:\tempAAA\src\GrampsAIO-4.2.2-1_win64.exe ..\..
Now you may backup your existing family trees and uninstall your old version of Gramps AIO and install the newly created version.
If you are a Gramps developer see Appendix A
Clean up
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
Indicating newer APPBUILD's
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):
https://codeload.github.com/gramps-project/gramps/zip/maintenance/gramps42
but in any case, if you have downloaded something other than a gramps-release tar.gz (or .zip) file, say this in your top directory (%g422%) (assuming you have installed Git for Windows):
git rev-list --count HEAD
and then
git rev-parse --short HEAD
and then put an "r" in front of the first string, followed by a hyphen ("-") and the second string, and then use the resulting combined string as your APPBUILD in the gramps.nsi
file, for clarity.
So for example your APPBUILD line might look like this:
!define APPBUILD "r23381-25018d6"
Then continue with the NSIS package building
Developers uploading to Sourceforge
If you are a developer and plan to upload it to SourceForge and it is an AIO of (a forthcoming) "master" put it into:
http://sourceforge.net/projects/gramps/files/Unstable
but if it is an AIO for a maintenance branch, make a Snapshots folder in that branch and put it there, e.g.:
http://sourceforge.net/projects/gramps/files/Stable/4.2.2/Snapshots
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.
Also see What to do for a release
Appendix B
Experimenting with NSIS compression
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.
Appendix C
Using AIO for development
If you plan to use the AIO for development with Gramps master(5.0+), and testing you many need to install the following additional programs:
pip
To install pip visit the following page for instruction:
https://pip.pypa.io/en/stable/installing/
Installing with get-pip.py
To install pip, securely download get-pip.py
https://bootstrap.pypa.io/get-pip.py
Then run the following:
python get-pip.py
From the Gramps AIO bin directory
meta package
The python package "meta"[1] is optional[2] but recommend for development and running test.
While in the Gramps AIO bin directory you can install "meta" with the following command:
pip install meta
[1] https://pypi.python.org/pypi/meta
[2] https://github.com/gramps-project/gramps#the-following-packages-are-optional
Contents
See also
- GrampsAIO-4
- All In One Gramps Software Bundle for Windows for the Gramps 3.4.x and earlier series
- Run Gramps40 for Windows from source using Python 2.7.3
- Gramps for Windows with MSYS2