View source for GrampsAIO-4 package updating

{{man warn|These instructions are obsolete as of Gramps 4.2.5.|Instead use <br>* [[Building Gramps AIO cx freeze-based]]}}
{{man warn|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.)

{{man note|Note|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.}}

{{man note|Note|In this tutorial you will only be 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.

{{man warn|NTFS partition|I believe that Gramps needs to have been installed in an NTFS partition (to preserve case-sensitive file names).}}

{{man note|Building older Gramps AIO's|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.}}

==== Download the old Gramps====
{{checkbox|0}} 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.

{{man note|Building Gramps development releases|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.)}}

{{checkbox|0}} 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

{{man warn|Power users building 32-bit or 64-bit versions|Note that both AIO versions can be built on 64-bit Windows.<br>whereas only the 32bit version can be built on 32-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.

{{checkbox|0}} In this tutorial we'll say you tell the installer to put it into a new "<code>C:\tempAAA</code>" 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 "<code>tempAAA</code>" in this tutorial to the actual name you used.  But every time I use "<code>tempAAA</code>" I mean the top of the tree where you installed the "old" AIO.

{{checkbox|0}} 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.
{{-}}
{{checkbox|0}} 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 ===
{{checkbox|0}} 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 ====

{{checkbox|0}} 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


{{man warn|Modify <code>C:\tempAAA\lib\python3.5\site-packages\gramps</code> above if required eg:<code>\python3.x\</code>|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.}}

{{man note|Other Gramps files|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 ===
==== Download Gramps source file ====
{{checkbox|0}} 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.

{{checkbox|0}} 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%

{{man note|If you are already in <code>C:\tempAAA\bin</code>|you can say <code>set path=%cd%;%path%</code> instead.}}

==== Install the updated Gramps source ====
{{checkbox|0}} Go to the decompressed 4.2.2 directory <code>C:\temp422\gramps-4.2.2</code>, 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%

{{checkbox|0}} 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.

{{man note|Optionally split the build into two parts|If you want to, you can split the "install" into its two parts -- the "build" and then the "install" -- by first running "python setup.py 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".

==== 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

{{checkbox|0}} 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 ====
{{checkbox|0}} The NSIS script file which controls how the Gramps AIO package is made is called <code>src\gramps.nsi</code> 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 <code>gramps.nsi</code> just in case, for instance onto your Desktop.

{{man note|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.}}

{{checkbox|0}} Then open the <code>C:\tempAAA\src\gramps.nsi</code> file with your favorite editor.

Part of the contents should look something like the following:
<pre>
!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"
</pre>

{{man note|Make sure your editor works|One user reported unicode problems with Notepad and then downloaded [https://notepad-plus-plus.org/ Notepad++] -- I used Wordpad, as I recall.}}

===== Increase the version number =====
{{checkbox|0}} 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 =====
{{checkbox|0}} 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).

{{man note|If you are a power user|and have downloaded something other than a tar.gz file, see [[GrampsAIO-4_package_updating#Appendix_A|Appendix A]] to change APPBUILD.}}

{{checkbox|0}} If necessary, change the BrandingText line to have the name of the new Gramps release instead of the old release name. 

{{man note|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.<br>See [[Previous releases of Gramps]]}}

{{checkbox|0}} 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  =====
{{checkbox|0}} Then save that gramps.nsi file, write it out.

==== Make the NSIS package  ====
{{checkbox|0}} If you are not already in that "src" folder, go there:

  cd C:\tempAAA\src

{{man warn|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.)

{{checkbox|0}} 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.
{{-}}
{{checkbox|0}} 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.

{{man warn|Please be patient|The NSIS package compression will probably take a while<br>'''-- OVER FIVE MINUTES FOR ME --'''}}

{{man note|Experimenting with NSIS compression|See [[GrampsAIO-4_package_updating#Appendix_B|Appendix B]] for power-user details, at this stage.}}

=== Conclusion ===

{{checkbox|0}} Assuming the compilation and compression were successful, move the resulting file out of the <code>C:\tempAAA\src</code> 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 [[GrampsAIO-4_package_updating#Appendix_A|Appendix A]]

==== Clean up ====
{{checkbox|0}} 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).
{{-}}
{{checkbox|0}} 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 <code>gramps.nsi</code> file, for clarity.

So for example your APPBUILD line might look like this:

  !define APPBUILD "r23381-25018d6"

Then continue with the [[GrampsAIO-4_package_updating#Increase_the_version_number|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

==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]]

[[Category:Documentation]]
[[Category:Developers/General]]