1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
Getting started with developing inkex
=====================================
.. highlight:: bash
.. warning::
This document is tailored for contributors to the inkex package and core extensions.
Extension authors should look here: :ref:`authors-tutorial`
Repository setup
----------------
It is possible to synchronize a fork with the extensions repository - whenever a branch in the
mirrored repository is updated, your fork will be updated too (usually with a delay of up to one
hour). See `Settings -> Repository -> Mirroring Repositories` and add a "Pull" mirror.
.. warning::
If you use this method, **do not** add commits to branches that should be synced
(such as `master`).
Depending on the exact settings of the mirroring option, you will either lose your changes,
lose the synchronisation or run into a messed up branch history.
Always check out submodules as well::
git submodule update && git submodule init
Python setup
------------
On every operating system, you need a working Python environment. Currently, inkex is tested
against Python 3.7-3.10.
inkex manages its dependencies using `poetry <https://python-poetry.org/docs/>`_. It can be installed using::
pip install poetry
Install the dependencies and the pre-commit hook::
poetry install
pre-commit install
Testing changes in Inkscape
---------------------------
Most of the time, calling the python file of the extension directly and through unit tests is
sufficient. In some cases, the interaction between Inkscape and the extension should be tested,
though.
Assuming you have managed to make Inkscape look in the correct folder for the extensions (see hints
for different operating systems below), the python
file of an extension is reloaded every time the extension is run. For changes to the inx file or
the command line parameters of the extension (as defined in the
:func:`~inkex.base.InkscapeExtension.add_arguments` method) you need to restart Inkscape.
Developing extensions on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. highlight:: batch
To test extensions with a given Inkscape version, download the 7z archive of that version,
unarchive it and delete the ``inkscape\share\extensions`` folder. Next, create a symlink in that
folder from an administrative command prompt::
cd [directory of the unzipped Inkscape folder]
mklink /D share\extensions C:\path\to\your\fork
If you start ``bin\inkscape`` now, the extensions are loaded from your fork.
Developing extensions on Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. highlight:: bash
A very similar path to Windows can be used when working off an appimage build.
Extract the appimage into a new folder called ``squashfs-root``::
/path/to/appimage --appimage-extract
squashfs-root/AppRun --system-data-directory
This prints the location of the extensions folder. Create a symlink to your repo there and run::
squashfs-root/AppRun
Trying / Changing a merge request locally
-----------------------------------------
Add this to ``git config -e`` (only once)::
[remote "upstream"]
url = git@gitlab.com:inkscape/extensions.git
fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
[alias]
mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' -
Check out the merge request !123::
git mr upstream 123
Push changes to the source branch ``source-branch-name`` of fork in the namespace (typically the
author's username) ``xyz``::
git push git@gitlab.com:xyz/extensions.git mr-origin-123:source-branch-name
Adding/Updating dependencies
----------------------------
.. highlight:: bash
The *direct* dependencies of inkex are declared in the ``pyproject.toml`` file.
There is also a lockfile named ``poetry.lock`` which has *all* the dependencies
(direct, dependencies of direct, dependencies of dependencies of direct and so on till the leaf dependencies)
pinned to specific versions (versions which were compatible the last time lockfile was updated).
To update all the dependencies in the lockfile to latest compatible versions, enter::
poetry lock
To add/update a particular dependency, add it to ``pyproject.toml`` manually. The dependency should be declared in the
``[tool.poetry.dependencies]`` TOML table, while a dependency required only during development of inkex should be declared in
``[tool.poetry.dev-dependencies]``.
Then update the lockfile using::
poetry lock
Alternatively, you can add a dependency and update the lockfile in a single command::
poetry add "lxml@^4.5.0" --lock
Both the ``pyproject.toml`` and ``poetry.lock`` are to be committed to the repository.
.. note::
You don't need to install the dependencies to add/update them. So, the commands above don't install anything.
However, if you are using poetry to manage the environment, and want to also install the dependencies,
remove the ``--lock`` options from the commands and use ``poetry update`` instead of ``poetry lock``.
.. note::
Dependencies should be updated according to the `policy <https://wiki.inkscape.org/wiki/Tracking_Dependencies#Distros>`_ defined in Inkscape wiki .
Creating a tag / publishing a version
-------------------------------------
1. Update the ``pyproject.toml`` file to the correct version number and push it to the target branch.
2. Create the tag (either on GitLab or offline + pushing)
3. Run ``poetry build``. This will create the wheel and the archive in the ``dist/`` folder.
4. Setup the ``~/.pypirc`` file according to `the instructions <https://packaging.python.org/en/latest/specifications/pypirc/>`_
5. Upload it: ``twine upload -r pypi dist/*``
6. Delete the contents of the dist folder: ``rm -r dist``
|
