Difference between revisions of "GrampsAIO-4 package updating"

From Gramps
Jump to: navigation, search
(Install the old Gramps)
(Download and install NSIS)
 
(30 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{man warn|Gramps 4.2 and later.|Any comments and help (e.g. on wiki pages) are welcome.}}
+
{{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.
 
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.
Line 23: Line 24:
  
 
==== Download the old Gramps====
 
==== Download the old Gramps====
So we will first download a Gramps AIO.
+
{{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.
 
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.
Line 29: Line 30:
 
{{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.)}}
 
{{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.)}}
  
So start by downloading the 4.2.1 AIO of Gramps.
+
{{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:
 
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:
Line 44: Line 45:
 
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.
 
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 "<code>C:\tempAAA</code>" folder.
+
{{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.)
 
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.)
Line 51: Line 52:
 
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.
 
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.
  
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}} 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.
+
{{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 ===
 
=== Modifying the old Gramps AIO ===
Now start a command-prompt window (Start=>Accessories) with executive power (right-click and "Run as administrator").
+
{{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.
 
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.
Line 77: Line 78:
 
==== Delete old Gramps files ====
 
==== Delete old Gramps files ====
  
Now delete some old Gramps files (or use Explorer to do it):
+
{{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\gramps
Line 84: Line 85:
  
 
   rmdir /s /q C:\tempAAA\lib\python3.5\site-packages\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 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.}}
Line 92: Line 96:
 
=== Installing the new Gramps tree ===
 
=== Installing the new Gramps tree ===
 
==== Download Gramps source file ====
 
==== 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:
+
{{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
 
   https://sourceforge.net/projects/gramps/files/Stable/4.2.2/gramps-4.2.2.tar.gz/download
  
 
==== Decompress/Extract the Gramps source file ====
 
==== 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.)
+
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.
 
You can put it almost any place you want since it is only temporary and you will remove it when you are done.
Line 103: Line 107:
 
But that folder can't be anywhere inside the C:\tempAAA  tree.  You must pick a location outside the C:\tempAAA tree.
 
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.
+
{{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:
 
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:
Line 117: Line 121:
  
 
==== Prepend folder paths ====
 
==== 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
+
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:
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%
 
   set path=C:\tempAAA\bin;%path%
  
(If you are already in C:\tempAAA\bin you can say
+
{{man note|If you are already in <code>C:\tempAAA\bin</code>|you can say <code>set path=%cd%;%path%</code> instead.}}
 
 
  set path=%cd%;%path%
 
 
 
instead.)
 
 
 
Once you have updated the el.po file (if you are upgrading to 4.2.2)
 
  
 
==== Install the updated Gramps source ====
 
==== Install the updated Gramps source ====
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):
+
{{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%
 
   cd %g422%
  
then say:
+
{{checkbox|0}} then say:
  
 
   python setup.py install --prefix=C:\tempAAA > C:\temp422\install-log.txt
 
   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
+
where the "prefix" argument is the folder name where you installed the old 4.2.1 Gramps AIO, C:\tempAAA in this tutorial.
tutorial.
 
  
Any errors should be typed on your command-shell screen. (At least they were for me, for instance complaints about
+
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.)
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
+
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.
"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.}}
 
{{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.}}
Line 158: Line 151:
 
https://en.wikipedia.org/wiki/Nullsoft_Scriptable_Install_System
 
https://en.wikipedia.org/wiki/Nullsoft_Scriptable_Install_System
  
Its homepage is http://nsis.sourceforge.net/Download and you should download the newest version (currently 3.0b3) and not the earlier version (currently 2.50).
+
{{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.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".)
+
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.)
 
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 ====
 
==== Modifying the gramps.nsi script ====
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.
+
{{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.}}
 
{{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.}}
  
Then open the <code>C:\tempAAA\src\gramps.nsi</code> file with your favorite editor.
+
{{checkbox|0}} Then open the <code>C:\tempAAA\src\gramps.nsi</code> file with your favorite editor.
  
The contents should look something like the following
+
Part of the contents should look something like the following:
 
<pre>
 
<pre>
 
!define APPNAME "GrampsAIO32"
 
!define APPNAME "GrampsAIO32"
Line 184: Line 175:
 
</pre>
 
</pre>
  
{{man note|Use Wordpad|One user reported unicode problems with Notepad and then downloaded [https://notepad-plus-plus.org/ Notepad++] -- I used Wordpad, as I recall.}}
+
{{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 =====
 
===== Increase the version number =====
Line 190: Line 181:
  
 
===== If needed update APPNAME and APPBUILD =====
 
===== 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.
+
{{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.}}
 
{{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.}}
  
If necessary, change the BrandingText line to have the name of the new Gramps release instead of the old release name.  
+
{{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]]}}
 
{{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]]}}
  
If necessary, edit the APP_PUBLISHER line to say "The Gramps project" instead of "The GRAMPS project".
+
{{checkbox|0}} If necessary, edit the APP_PUBLISHER line to say "The Gramps project" instead of "The GRAMPS project".
  
===== If required add path to pyconfig.h =====
+
===== 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.
 
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.
  
Line 213: Line 204:
  
 
===== Save the file  =====
 
===== Save the file  =====
Then save that gramps.nsi file, write it out.
+
{{checkbox|0}} Then save that gramps.nsi file, write it out.
  
===== Make the NSIS package  =====
+
==== Make the NSIS package  ====
If you are not already in that "src" folder, go there:
+
{{checkbox|0}} If you are not already in that "src" folder, go there:
  
 
   cd C:\tempAAA\src
 
   cd C:\tempAAA\src
Line 226: Line 217:
 
So there are two other possibilities.  (I did it both ways (GUI and CLI) and both worked for me.)
 
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.
+
{{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.
 
+
{{-}}
The other way is to type the full pathname to the compiler, which in my case was:
+
{{checkbox|0}} The other way is to type the full pathname to the compiler, which in my case was:
  
 
   C:\NSIS\makensis gramps.nsi
 
   C:\NSIS\makensis gramps.nsi
  
{{man warn|Please be patient|The NSIS package compression will probably take a while<br>-- OVER FIVE MINUTES FOR ME --}}
+
Note that after the compilation, the resulting files will be compressed.
  
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.}}
 
{{man note|Experimenting with NSIS compression|See [[GrampsAIO-4_package_updating#Appendix_B|Appendix B]] for power-user details, at this stage.}}
Line 240: Line 231:
 
=== Conclusion ===
 
=== Conclusion ===
  
Assuming the compilation and compression were successful, move the resulting file out of the <code>C:\tempAAA\src</code> folder:
+
{{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:
 
For the 32 bit version:
Line 255: Line 246:
  
 
==== Clean up ====
 
==== 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).
+
{{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).
 
+
{{-}}
Similarly, the gramps-4.2.2 tree may be deleted (%g422%).
+
{{checkbox|0}} Similarly, the gramps-4.2.2 tree may be deleted (%g422%).
  
 
=== Appendix A ===
 
=== Appendix A ===
Line 265: Line 256:
 
   https://codeload.github.com/gramps-project/gramps/zip/maintenance/gramps42
 
   https://codeload.github.com/gramps-project/gramps/zip/maintenance/gramps42
  
but in any case, if you have downloaded something other than a tar.gz file, say this in your top directory (%g422%) (Assuming you have installed Git for windows):
+
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
 
   git rev-list --count HEAD
Line 273: Line 264:
 
   git rev-parse --short HEAD
 
   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 in the gramps.nsi file, for clarity.
+
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:
 
So for example your APPBUILD line might look like this:
Line 305: Line 296:
  
 
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'''.
 
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==
 
==See also==
 
* [[GrampsAIO-4]]
 
* [[GrampsAIO-4]]
 
* [[All In One Gramps Software Bundle for Windows]] for the Gramps 3.4.x and earlier series
 
* [[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:Documentation]]
 
[[Category:Developers/General]]
 
[[Category:Developers/General]]

Latest revision as of 03:42, 18 September 2019

Gnome-important.png
These instructions are obsolete as of Gramps 4.2.5.

Instead use
* Building Gramps AIO cx freeze-based

Gnome-important.png
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.)

Gramps-notes.png
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.

Gramps-notes.png
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.

Gnome-important.png
NTFS partition

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

Gramps-notes.png
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

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.

Gramps-notes.png
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.)

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
Gnome-important.png
Power users building 32-bit or 64-bit versions

Note that both AIO versions can be built on 64-bit Windows.
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.

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


Gnome-important.png
Modify C:\tempAAA\lib\python3.5\site-packages\gramps above if required eg:\python3.x\

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.

Gramps-notes.png
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

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%
Gramps-notes.png
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.

Gramps-notes.png
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

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.

Gramps-notes.png
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"
Gramps-notes.png
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).

Gramps-notes.png
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.

Gramps-notes.png
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.
See Previous releases of Gramps

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
Gnome-important.png
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.

Gnome-important.png
Please be patient

The NSIS package compression will probably take a while
-- OVER FIVE MINUTES FOR ME --

Gramps-notes.png
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

See also