/usr/share/doc/gnat-gps/html/Customization-files-and-plugins.html is in gnat-gps-doc 5.0-6.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 | <html lang="en">
<head>
<title>Customization files and plugins - Using the GNAT Programming Studio</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Using the GNAT Programming Studio">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files" title="Customizing through XML and Python files">
<link rel="next" href="Defining-Actions.html#Defining-Actions" title="Defining Actions">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 2002-2010 AdaCore.
This document is free; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, see `http://www.gnu.org/licenses/'.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
pre.smallexample {background-color:rgb(240,240,240);
font-family: courier new,courier,fixed;
font-size: 14px;
margin: 0px 40px 0px 40px;
border-width: 1px 2px 2px 1px;
border-top-style: dotted;
border-left-style: dotted;
border-right-style: solid;
border-bottom-style: solid;
border-color: black;}
code {color:black;
font-family: courier new,courier,fixed;
font-size: 14px;}
body {font-family: arial,helvetica,sans-serif;
font-size: 16px;
max-width: 800px;
text-align: justify}
samp {font-family: courier new,courier,fixed;
font-size: 14px}
--></style>
</head>
<body>
<div class="node">
<a name="Customization-files-and-plugins"></a>
<p>
Next: <a rel="next" accesskey="n" href="Defining-Actions.html#Defining-Actions">Defining Actions</a>,
Up: <a rel="up" accesskey="u" href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files">Customizing through XML and Python files</a>
<hr>
</div>
<h4 class="subsection">16.5.1 Customization files and plugins</h4>
<!-- -->
<p class="noindent">You can customize lots of capabilities in GPS using files that are
loaded by GPS at start up.
<p>For example, you can add items in the menu and tool bars, as well as
defining new key bindings, new languages, new tools, <small class="dots">...</small>;
Using Python as a programming language, you can also add brand new facilities
and integrate your own tools in the GPS platform.
<p>These customization files are searched for at startup in several different
places. Depending on the location where they are found, these files will either
be automatically loaded by GPS (and thus can immediately modify things in GPS),
or will simply be made visible in the Plug-ins Editor
(see <a href="The-Plug_002dins-Editor.html#The-Plug_002dins-Editor">The Plug-ins Editor</a>).
<p>These directories are searched for in the order given below. Any script loaded
latter can override setups done by previously loaded scripts. For instance,
they could override a key shortcut, remove a menu, redefining a GPS
action, <small class="dots">...</small>
<p>In the directory names below, <samp><span class="file">INSTALL</span></samp> is the name of the directory in
which you have installed GPS. <samp><span class="file">HOME</span></samp> is the user's home directory, either
by default or as overriden by the <code>GPS_HOME</code> environment variable. If none
of these exist, GPS will use the <code>USERPROFILE</code> environment variable.
<p>In all these directories, only the files with <samp><span class="file">.xml</span></samp> or <samp><span class="file">.py</span></samp>
extensions are taken into account. Other files are ignored, although for
compatibility with future versions of GPS it is recommended not to keep other
files in the same directory.
<ul>
<li>Automatically loaded system wide modules
<p>The <samp><span class="file">INSTALL/share/gps/plug-ins</span></samp> directory should contain the files that
GPS will automatically load by default (unless overriden by the user through
the Plug-ins Editor). These plug-ins are visible to any user on the
system that uses the same GPS installation. This directory should be reserved
for critical plug-ins that almost every one should use.
<li>Not automatically loaded system wide modules
<p>The <samp><span class="file">INSTALL/share/gps/library</span></samp> directory should contain the files that
GPS should show in the Plug-ins Editor, but not load automatically.
Typically, these would be files that add optional capabilities to GPS, for
instance an emacs emulation mode, or additional editor capabilities that a lot
of users would not generally use.
<li><code>GPS_CUSTOM_PATH</code>
<p>This environment variable can be set before launching GPS. It should contain
a list of directories, separated by semicolons (';') on Windows systems and
colons (':') on Unix systems. All the files in these directories with the
appropriate extensions will be automatically loaded by default by GPS,
unless overriden by the user through the Plug-ins Editor.
<p>This is a convenient way to have project-specific customization files. You can
for instance create scripts, or icons, that set the appropriate value for the
variable and then start GPS. Depending on your project, this allows you to
load specific aliases which do not make sense for other projects.
<li>Automatically loaded user directory
<p>The directory <samp><span class="file">HOME/.gps/plug-ins</span></samp> is searched last. Any script
found in there will be automatically loaded unless overriden in the
Plug-ins Editor.
<p>This is a convenient way for users to create their own plug-ins, or
test them before they are made available to the whole system by
copying them to one of the other directories.
</ul>
<p>Any script loaded by GPS can contain customization for various aspects
of GPS, mixing aliases, new languages or menus, <small class="dots">...</small> in a single
file. This is a convenient way to distribute your plug-ins to other
users.
<h5 class="subsubsection">16.5.1.1 Python files</h5>
<p>Although the format of the python plug-ins is free (as long as it can
be executed by Python), the following organization is suggested. These
plug-ins will be visible in the Plug-ins Editor, and therefore having
a common format makes it easier for users to understand the goal of the
plug-ins:
<ul>
<li>Comment
<p>The first part of the script should be a general comment on the goal and
usage of the script. This comment should use python's triple-quote
convention, rather than start-of-line hash ('#') signs.
<p>The first line of the comment should be a one liner explaining the goal
of the script. It is separated by a blank line from the rest of the
comment.
<p>The rest of the comment is free-form.
<li>Customization variables
<p>If your script can be configured by the user by changing some global
variables, they should be listed in their own section, and fully
documented. The user can then, through the /Tools/Plug-ins editor
change the value of these variables
<li>Implementation
<p>The implementation should be separated from the initial comment by a
form-feed (control-L) character. The startup scripts editor will know
not to display the rest of the script on the first page of the editor.
<p>Generally speaking, scripts should avoid executing code as soon as they
are loaded. This gives a chance to the user to change the value of global
variables or even override functions before the script is actually launched.
<p>The solution is to connect to the <code>"gps_started"</code> hook, as in
<pre class="smallexample"> ^L
###########################################################
## No user customization below this line
###########################################################
import GPS
def on_gps_started (hook_name):
... launch the script
GPS.Hook ("gps_started").add (on_gps_started)
</pre>
</ul>
<h5 class="subsubsection">16.5.1.2 XML files</h5>
<p>XML files must be utf8-encoded by default. In addition, you can
specify any specific encoding through the standard <code><?xml
encoding="..." ?></code> declaration, as in the following example:
<pre class="smallexample"> <?xml version="1.0" encoding="iso-8859-1"?>
<!-- general description -->
<submenu>
<title>encoded text</title>
</submenu>
</pre>
<p>These files must be valid XML files, i.e. must start with the
<code><?xml?></code> tag, and contain a single root XML node, the name of which is
left to your consideration. The general format is therefore
<pre class="smallexample"> <?xml version="1.0" ?>
<root_node>
...
</root_node>
</pre>
<p>It is also recommended that the first line after the <code><?xml?></code> tag
contains a general comment describing the purpose and usage of the script.
This comment will be made visible in the Plug-ins editor.
<p>The list of valid XML nodes that can be specified under <root> is
described in later sections. It includes:
<dl>
<dt><code><action></code><dd>(see <a href="Defining-Actions.html#Defining-Actions">Defining Actions</a>)
<br><dt><code><key></code><dd>(see <a href="Binding-actions-to-keys.html#Binding-actions-to-keys">Binding actions to keys</a>)
<br><dt><code><submenu></code><dd>(see <a href="Adding-new-menus.html#Adding-new-menus">Adding new menus</a>)
<br><dt><code><pref></code><dd> (see <a href="Preferences-support-in-custom-files.html#Preferences-support-in-custom-files">Preferences support in custom files</a>)
<br><dt><code><preference></code><dd> (see <a href="Preferences-support-in-custom-files.html#Preferences-support-in-custom-files">Preferences support in custom files</a>)
<br><dt><code><alias></code><dd>(see <a href="Defining-text-aliases.html#Defining-text-aliases">Defining text aliases</a>)
<br><dt><code><language></code><dd> (see <a href="Adding-support-for-new-languages.html#Adding-support-for-new-languages">Adding support for new languages</a>)
<br><dt><code><button></code><dd> (see <a href="Adding-tool-bar-buttons.html#Adding-tool-bar-buttons">Adding tool bar buttons</a>)
<br><dt><code><entry></code><dd> (see <a href="Adding-tool-bar-buttons.html#Adding-tool-bar-buttons">Adding tool bar buttons</a>)
<br><dt><code><vsearch-pattern></code><dd> (see <a href="Defining-new-search-patterns.html#Defining-new-search-patterns">Defining new search patterns</a>)
<br><dt><code><tool></code><dd> (see <a href="Adding-support-for-new-tools.html#Adding-support-for-new-tools">Adding support for new tools</a>)
<br><dt><code><filter></code><dd> (see <a href="Filtering-actions.html#Filtering-actions">Filtering actions</a>)
<br><dt><code><contextual></code><dd> (see <a href="Adding-contextual-menus.html#Adding-contextual-menus">Adding contextual menus</a>)
<br><dt><code><case_exceptions></code><dd> (see <a href="Adding-casing-exceptions.html#Adding-casing-exceptions">Adding casing exceptions</a>)
<br><dt><code><documentation_file></code><dd> (see <a href="Adding-documentation.html#Adding-documentation">Adding documentation</a>)
<br><dt><code><doc_path></code><dd> (see <a href="Adding-documentation.html#Adding-documentation">Adding documentation</a>)
<br><dt><code><stock></code><dd> (see <a href="Adding-stock-icons.html#Adding-stock-icons">Adding stock icons</a>)
<br><dt><code><project_attribute></code><dd> (see <a href="Defining-project-attributes.html#Defining-project-attributes">Defining project attributes</a>)
<!-- @item <docgen_backend> -->
<!-- (@pxref{Defining a documentation format}) -->
<br><dt><code><remote_machine_descriptor></code><dd> (see <a href="Defining-a-remote-server.html#Defining-a-remote-server">Defining a remote server</a>)
<br><dt><code><remote_path_config></code><dd> (see <a href="Defining-a-remote-path-translation.html#Defining-a-remote-path-translation">Defining a remote path translation</a>)
<br><dt><code><remote_connection_config></code><dd> (see <a href="Defining-a-remote-connection-tool.html#Defining-a-remote-connection-tool">Defining a remote connection tool</a>)
<br><dt><code><rsync_configuration></code><dd> (see <a href="Configuring-rsync-usage.html#Configuring-rsync-usage">Configuring rsync usage</a>)
</dl>
<!-- -->
</body></html>
|