3,146
edits
Changes
From Gramps
Use {{Stable_branch}} as recommended
{{man tip|Information on developing Gramps addons|If you are looking for addons to install, visit: [[Third-party Addons]]}}
{{man warn|Note that this article anticipates that most addons will be developed under Linux.|([[Getting started with Gramps development|Linux is the principal development platform.]]) While it is possible to do so under Windows or MacOS, some of the steps will differ and the documented processes have not been as thoroughly reviewed. So developer beware.<br>See [[Portal:Developers]]}}
{{man note|More upto date information:|* https://github.com/gramps-project/addons-source/blob/maintenance/gramps60gramps{{Stable_branch}}/CONTRIBUTING.md<br>* https://github.com/gramps-project/addons-source/blob/maintenance/gramps60gramps{{Stable_branch}}/MAINTAINERS.md}}
If you are developing a [[Third-party Addons|Third-party Addon]]; this page documents the API, methods, and best practices for Gramps 4.2 and later.
== 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/gramps60 gramps{{Stable_branch}} git branch, as the default is master branch for the developmental pre-release. (Currently gramps 6.1, which is not the typical target for addons.)
Example commands are shown below referring to the public release rather than the master branch.
*** /download
*** /listings
** [https://github.com/gramps-project/addons/tree/master/gramps60 gramps{{Stable_branch}} /gramps60gramps{{Stable_branch}}]
*** /download
*** /listings
git clone https://github.com/gramps-project/gramps.git gramps
To switch to a local copy of the gramps60 gramps{{Stable_branch}} maintenance branch:
cd addons-source
git checkout -b gramps60 gramps{{Stable_branch}} origin/maintenance/gramps60gramps{{Stable_branch}}
or to work in the master branch:
* Remove the files using the ''clean'' command that should not be added to GitHub (eg files(template.pot/ locale etc)):
: <code>./make.py gramps60 gramps{{Stable_branch}} 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 gramps60gramps{{Stable_branch}}</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 gramps60 gramps{{Stable_branch}} build all</code>
To compile translations for all projects :
: <code>python3 make.py gramps60 gramps{{Stable_branch}} compile all</code>
== Create a Gramps Plugin Registration file ==
* Initialize and update the <code>template.pot</code> for your addon:
: <code>cd ~/addons-source</code>
: <code>./make.py gramps60 gramps{{Stable_branch}} 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 gramps60 gramps{{Stable_branch}} init NewProjectName fr</code>
* Update it from gramps and other addons:
: <code>./make.py gramps60 gramps{{Stable_branch}} update NewProjectName fr</code>
* Edit the translations file manually:
: <code>/NewProjectName/po/fr-local.po</code>
* Compile the language:
: <code>./make.py gramps60 gramps{{Stable_branch}} 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 gramps60gramps{{Stable_branch}}</code>
{{man tip|From Gramps 6.x translations can be done on Weblate. This is experimental. Initial testing has appeared successful, but please let us know if you notice any problems. The Weblate Addons component contains aggregated translations for every addon.|https://hosted.weblate.org/projects/gramps-project/addons/}}<!-- https://gramps-project.org/bugs/view.php?id=13646#c68218 Nick Hall "Weblate is set up to translate the gramps60 gramps{{Stable_branch}} branch. Changes to gramps52 must still use the old manual process." -->
== Package your addon ==
To create a downloadable package:
: <code>./make.py gramps60 gramps{{Stable_branch}} build NewProjectName</code> or
: <code>./make.py gramps61 build NewProjectName</code> for the master branch.
<pre> cd '~/addons'
git add gramps60gramps{{Stable_branch}}/download/NewProjectName.addon.tgz
git commit -m "Added new plugin: NewProjectName"</pre>
or (for the master branch);
== List your addon in the Gramps Plugin Manager==
{{man warn|Gramps needs to have been built|Make sure you have already built gramps60 gramps{{Stable_branch}} 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 gramps60 gramps{{Stable_branch}} listing NewProjectName</code>
or (for the master branch);
: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
<pre> cd '~/addons'
git add gramps60gramps{{Stable_branch}}/listings/*
git commit -m "Added new plugin to listings: NewProjectName"</pre>
or (for the master branch);
