4,216
edits
Changes
→Get a local copy of Gramps and its addons
Addons for Gramps can extend the program in many different ways. You can add any of the following [https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py types] of addons:
==Writing an addon==
# [[#List_and_document_your_addon_on_the_wiki|Document your addon]] and publish it to the addon list
# [[#List_your_addon_in_the_Gramps_Plugin_Manager|Register your addon with the Plugin Manager]]
# [[#Announce_it_on_the_Gramps_mailing_listAnnounce_the_addon|Announce it on the Gramps mailing listForum]] - Let users know it exist and how to use it.
# [[#Support_it_through_issue_tracker|Support it through the issue tracker]]
# [[#Maintain_the_code_as_Gramps_continues_to_evolve|Maintain the code]] as Gramps continues to evolve
== Develop your addon ==
The [http://github.com/gramps-project/addons-source addons-source] repository holds the source code for the addons with branches holding the version for different gramps. If you are working on an addon for gramps for the current Gramps {{man version}} public release, be sure to use the maintenance/gramps52 git branch, as the default is master branch for the developmental pre-release. (Currently gramps 5.3, which is not the typical target for addons.) Example commands are shown below referring to the public release rather than the master branch. The developers are currently merging changes to the most recent maintenance branch into master as necessary, so you don't have to do anything for that unless you are in a hurry. The [http://github.com/gramps-project/addons-source addons-source] git repository has the following structure, with the code for each addon in its own folder:
* /addons-source
** ...
The [http://github.com/gramps-project/addons addons] git repository holds built versions of the addons for each release of Gramps, and has the following structure:
* /addons
** [https://github.com/gramps-project/addons/tree/master/gramps42 /gramps42]*** /download*** /listings** [https://github.com/gramps-project/addons/tree/master/gramps50 /gramps50]
*** /download
*** /listings
** [https:/gramps50/github.com/gramps-project/addons/tree/master/gramps51 /gramps51]
*** /download
*** /listings
** [https:/gramps51/github.com/gramps-project/addons/tree/master/gramps52 /gramps52]
*** /download
*** /listings
=== Get a local copy of Gramps and its addons ===
# Get an https://github.com/join account if you don't already have one.
# Request GIT write access for the https://github.com/gramps-project/addons-source project by emailing the [[Contact#Mailing_lists|gramps-devel mailing list]]
See also [[Brief_introduction_to_Git|git introduction]] for instructions on installing git and getting basic settings configured. Also [https://help.github.com/articles/generating-an-ssh-key/ Connecting to GitHub with SSH] will help with setting up credentials for GitHub.
To fully build and advertise a new addon will require local copies of the three repositories, the 'addons-source', 'addons' and the main Gramps source 'gramps'.
This wiki assumes that the all three git repositories local locations are all to be put into the users' home same base directory and named with the repository names. The three directories '''must''' be named as shown, and in the same base directory in order for the make.py script commands to work properlyas shown. From the base directory, however they don't have run the following commands to be located directory in the users home directorycreate a copy of each repository. From your home directoryIf you want to use SSH;
git clone [email protected]:gramps-project/addons-source.git addons-source
git clone [email protected]:gramps-project/gramps.git gramps
or if you do not have want to use a Github accountweb url:
git clone https://github.com/gramps-project/addons-source.git addons-source
git clone https://github.com/gramps-project/gramps.git gramps
cd addons-source
git checkout -b gramps51 gramps52 origin/maintenance/gramps51gramps52
or to work in the master branch:
cd addons-source
git checkout -b gramps52 gramps53 origin/master
=== Other pre-requisites prerequisites ===
{{man warn|These instructions, the make.py script etc.|are designed to operate in a Linux environment. {{man menu|They won't work on Windows without modifications.}}}}
* Gramps uses Python version 3.2 or higher. You must have at least that version installed. If you have installed Gramps 4.2 or higher on your Linux system already, then a sufficient version of Python will be present. If you have more than one version of Python installed, then you must use the correct version for these scripts. On some systems, both Python 2.x and 3.x are installed. It is possible that the normal invocation of <code>python</code> starts up Python 2.x, and that to start up Python 3.x requires invoking with <code>python3</code> or <code>python3.4</code> etc. You can test the version by <code>python –version</code> or <code>python3 –version</code>. If this is so, replace any usage of 'python' in the examples below with the appropriate invocation.
* Remove the files using the ''clean'' command that should not be added to GitHub (eg files(template.pot/ locale etc)):
: <code>./make.py gramps51 gramps52 clean NewProjectName</code>
* Add the project to the repository:
: <code>git add NewProjectName</code>
* to make sure that outside changes do not affect your commit
: <code>git pull --rebase</code>
: <code>git push origin gramps51gramps52</code>
Also you may want to [[Addons_development#Package_your_addon |Package your addon]] so it can be downloaded via the plugin manager.
To build and compile translations for all projects to their download/Addon.addon.tgz files:
: <code>python3 make.py gramps51 gramps52 build all</code>
To compile translations for all projects :
: <code>python3 make.py gramps51 gramps52 compile all</code>
== Create a Gramps Plugin Registration file ==
<pre>
register(PTYPE,
gramps_target_version = "5.12",
version = "1.0.0",
ATTR = value,
description = _("Attaches a shared source to multiple objects."),
version = '1.0.0',
gramps_target_version = '5.12',
status = STABLE,
fname = 'AttachSourceTool.py',
</pre>
You can see examples of the kinds of addons [https://github.com/gramps-project/gramps/plugins here] (for example, see [https://github.com/gramps-project/gramps/plugins/drawreport/drawplugins.gpr.py gramps/plugins/drawreport/drawplugins.gpr.py]) and see the full documentation in the [https://github.com/gramps-project/gramps/blob/3f0db9303f29811b43325c30149c8844c7ce24b6/gramps/gen/plug/_pluginreg.py#L23 master/gramps/gen/plug/_pluginreg.py here] in the comments and docstrings.
Note that this .gpr.py will automatically use translations if you have them (see below). That is, the function "_" is predefined to use your locale translations; you only need to mark the text with _("TEXT") and include a translation of "TEXT" in your translation file. For example, in the above example, _("Attach Source") is marked for translation. If you have developed and packaged your addon with translation support, then that phrase will be converted into the user's language.
=== Report plugins ===
The possible report categories are ([https://github.com/gramps-project/gramps/blob/892fc270592095192947097d22a72834d5c70447/gramps/gen/plug/_pluginreg.py#L141-L149 gen/plug/_pluginreg.py]):
<pre>
#possible report categories
CATEGORY_BOOK = 4
CATEGORY_GRAPHVIZ = 5
CATEGORY_TREE = 6
REPORT_CAT = [ CATEGORY_TEXT, CATEGORY_DRAW, CATEGORY_CODE,
CATEGORY_WEB, CATEGORY_BOOK, CATEGORY_GRAPHVIZ, CATEGORY_TREE]
</pre>
description = _("Provides a library for doing something."),
version = '1.0',
gramps_target_version = '5.12',
status = STABLE,
fname = 'library.py',
category = "WEBSTUFF",
version = '1.0',
gramps_target_version = '5.12',
data = ["a", "b", "c"],
)
description = _("Provides a collection of stylesheets for the web"),
version = '1.0',
gramps_target_version = '5.12',
fname = "stylesheet.py",
load_on_reg = True,
<span id=internationalization>
== List the Prerequistes your addon depends on ==
''In your gpr file, you can have a line like:
<code>depends_on = ["libwebconnect"]</code>
which is a list of id's from other gpr files. This example will ensure that [[Addon:Web_Connect_Pack#Prerequisites|libwebconnect]] is loaded before your addon. If it can't be found, or you have a cycle, then your addons won't be loaded.
example code used in the Addon:Web_Connect_Pack that references libwebconnect Prerequistes [https://github.com/gramps-project/addons-source/blob/1304b65a7d758bfe17339c26260473ac3e9c4061/RUWebConnectPack/RUWebPack.gpr.py#L17 RUWebPack.gpr.py#L17 ]
This means that common Prerequistes can be shared between addons and that code sits in its own gpr/addon file.
<!--
[] for addon prerequistes have a look at converting them to use "depends_on = " like in the following addons
https://github.com/gramps-project/addons-source/search?utf8=%E2%9C%93&q=depends_on&type=
https://github.com/gramps-project/gramps/search?utf8=%E2%9C%93&q=depends_on&type=
which can be a comma separated list for multiple dependencies/prerequisites (so that addons that share prerequisites import the same library?) (maybe move spell check into an addon etc? tip of the day... possibilities...)
depends_on = ["libwebconnect"]
mentioned in the following
https://sourceforge.net/p/gramps/mailman/message/27070037/
''In your gpr file, you can have a line like:
depends_on = ["libwebconnect"]
which is a list of id's from other gpr files. This example will ensure
that libwebconnect is loaded before your plugin. If it can't be found,
or you have a cycle, then your plugin won't be loaded.
If it is a common function, perhaps libhtml is the right place to put
it, and you can put a depends_on on that.
-Doug''
example output is on terminal only:
Cannot resolve the following plugin dependencies:
Plugin 'UK Web Connect Pack' requires: ['libwebconnect']
[](feature) For plugins/addons if prerequisites not available display a page stating why/what is missing that includes the addon description and a url to the support page.
[] Gramps CLI info "gramps -v" needs a section that list third-party addons with version numbers and if prerequisites have been met.
[]update the Addon:Prerequisites Checker Gramplet to test for your Prerequisites.
-->
== Get translators to translate your addon into multiple languages ==
</span>
* Initialize and update the <code>template.pot</code> for your addon:
: <code>cd ~/addons-source</code>
: <code>./make.py gramps51 gramps52 init NewProjectName</code>
* You should edit the header of <code>template.pot</code> with your information, so it gets copied to individual language files.
* Initialize a language for your addon (say French, fr):
: <code>./make.py gramps51 gramps52 init NewProjectName fr</code>
* Update it from gramps and other addons:
: <code>./make.py gramps51 gramps52 update NewProjectName fr</code>
* Edit the translations file manually:
: <code>/NewProjectName/po/fr-local.po</code>
* Compile the language:
: <code>./make.py gramps51 gramps52 compile NewProjectName</code>
* Add or update your local language file, and commit changes:
: <code>git add NewProjectName/po/fr-local.po</code>
: <code>git commit NewProjectName/po/fr-local.po -m "Added fr po file"</code>
* If you have been given 'push' rights to GitHub 'gramps-project/addons-source', then;
: <code>git push origin gramps51gramps52</code>
== Package your addon ==
To create a downloadable package:
: <code>./make.py gramps51 gramps52 build NewProjectName</code> or: <code>./make.py gramps52 gramps53 build NewProjectName</code> for the master branch. Note that the
This will automatically include the following files in your build:
<pre> cd '~/addons'
git add gramps51gramps52/download/NewProjectName.addon.tgz
git commit -m "Added new plugin: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps52gramps53/download/NewProjectName.addon.tgz
git commit -m " Added new plugin: NewProjectName"</pre>
== List your addon in the Gramps Plugin Manager==
{{man warn|Gramps needs to have been built|Make sure you have already built gramps51 gramps52 or master. Change to the appropriate git branch in your gramps directory, and run <code>python3 setup.py build</code> See [[Linux:Build_from_source]]}}
To create a listing:
: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps51 gramps52 listing NewProjectName</code>
or (for the master branch);
: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps52 gramps53 listing NewProjectName</code>
That will create a series of files in the <tt>../listings/</tt> directory.
<pre> cd '~/addons'
git add gramps51gramps52/listings/*
git commit -m "Added new plugin to listings: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps52gramps53/listings/*
git commit -m " Added new plugin to listings: NewProjectName"</pre>
===List your addon===
Add a short description of your addon to the Addons list by editing the current release listing eg: [[5.1_Addons2_Addons]] or if the addon is meant for a future release [[5.2_Addons3_Addons]] when available.
==== Example addon template ====
</pre>
== Announce it on the Gramps mailing list addon ==Join the [[Contact#Mailing_listsForum|Gramps Mailing listsForum]] and announce it to the users with general information on why you created and how to use it.
== Support it through issue tracker ==
== Maintain the code as Gramps continues to evolve ==
{{man tip|When submitting an update the patch part of the version number MAJOR.MINOR.PATCH is updated during the addon build process e.g. 1.1.3 to 1.1.4|You can find this step in [https://github.com/gramps-project/addons-source/blob/master/make.py#L125 addons-source/make.py].[https://gramps.discourse.group/t/should-addons-pr-include-version-number-update/2591]}} Remember that Gramps addons exist for many reasons and there are manyGramps developers that do support addons in various ways (translations,triage, keeping in sync with master, download infrastructure, etc).
Some reasons why the addons exist; they provide:
* A place for controversial plugins that will never be accepted into core, but are loved by many users (eg, Data Entry Gramplet).
* A place for experimental components to live.
== Example code adding common enhancements ==
* Copy all the Gramplet's output to a system clipboard via context pop-up menu : Enhancement request {{bug|11573}}, [https://github.com/gramps-project/gramps/pull/1014/commits/72012e13b4ca15caca4b7f36fdb9702c1fd470fd example pull]
;Gramps Addons site for Gramps 4.1 and older
* For 4.1.x and earlier, see [[Addons development old]].
= Addon Development Tutorials and Samples =
* [[Report-writing_tutorial|Report-writing Tutorial]]
* [[Quick_Views|Quick Views]]
* [[Gramplets|Gramplets]]
* [[Develop_an_Add-on_Rule|Develop an Add-on Rule]]
* [[Develop_an_Add-on_Tool|Develop an Add-on Tool]]
* [[Adapt_a_built-in_Report|Adapt a built-in Report]]
[[Category:Developers/General]]
