|
Packit |
1470ea |
|
|
Packit |
1470ea |
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="namespacing" xml:lang="el">
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<info>
|
|
Packit |
1470ea |
<link type="guide" xref="index#maintainer-guidelines"/>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<credit type="author copyright">
|
|
Packit |
1470ea |
<name>Philip Withnall</name>
|
|
Packit |
1470ea |
<email its:translate="no">philip.withnall@collabora.co.uk</email>
|
|
Packit |
1470ea |
<years>2015, 2016</years>
|
|
Packit |
1470ea |
</credit>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<desc>
|
|
Packit |
1470ea |
Avoiding symbol conflicts between libraries by namespacing all APIs
|
|
Packit |
1470ea |
</desc>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
|
|
Packit |
1470ea |
<mal:name>Ελληνική μεταφραστική ομάδα GNOME</mal:name>
|
|
Packit |
1470ea |
<mal:email>team@gnome.gr</mal:email>
|
|
Packit |
1470ea |
<mal:years>2016</mal:years>
|
|
Packit |
1470ea |
</mal:credit>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
|
|
Packit |
1470ea |
<mal:name>Θάνος Τρυφωνίδης</mal:name>
|
|
Packit |
1470ea |
<mal:email>tomtryf@gnome.org</mal:email>
|
|
Packit |
1470ea |
<mal:years>2016</mal:years>
|
|
Packit |
1470ea |
</mal:credit>
|
|
Packit |
1470ea |
</info>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<title>Namespacing</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<synopsis>
|
|
Packit |
1470ea |
<title>Σύνοψη</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
If a library is namespaced correctly, it can define types and methods in
|
|
Packit |
1470ea |
its API which have the same names as those in another library, and a
|
|
Packit |
1470ea |
program can use both without conflicts. This is achieved by prefixing all
|
|
Packit |
1470ea |
types and method names with a namespace unique to the library.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
</synopsis>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<section id="gobject">
|
|
Packit |
1470ea |
<title>GObject API</title>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Consistent and complete namespacing of symbols (functions and types) and
|
|
Packit |
1470ea |
files is important for two key reasons:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<list type="numbered">
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
Establishing a convention which means developers have to learn fewer
|
|
Packit |
1470ea |
symbol names to use the library — they can guess them reliably instead.
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
Ensuring symbols from two projects do not conflict if included in the
|
|
Packit |
1470ea |
same file.
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
</list>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
The second point is important — imagine what would happen if every project
|
|
Packit |
1470ea |
exported a function called create_object() . The headers
|
|
Packit |
1470ea |
defining them could not be included in the same file, and even if that
|
|
Packit |
1470ea |
were overcome, the programmer would not know which project each function
|
|
Packit |
1470ea |
comes from. Namespacing eliminates these problems by using a unique,
|
|
Packit |
1470ea |
consistent prefix for every symbol and filename in a project, grouping
|
|
Packit |
1470ea |
symbols into their projects and separating them from others.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
The conventions below should be used for namespacing all symbols. They are
|
|
Packit |
1470ea |
<link href="https://developer.gnome.org/gobject/stable/gtype-conventions.html">
|
|
Packit |
1470ea |
used in all GLib-based projects</link>, so should be familiar to a lot of
|
|
Packit |
1470ea |
developers:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<list>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
Functions should use lower_case_with_underscores .
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
Structures, types and objects should use
|
|
Packit |
1470ea |
CamelCaseWithoutUnderscores .
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
Macros and constants should use
|
|
Packit |
1470ea |
UPPER_CASE_WITH_UNDERSCORES .
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
All symbols should be prefixed with a short (2–4 characters) version of
|
|
Packit |
1470ea |
the namespace. This is shortened purely for ease of typing, but should
|
|
Packit |
1470ea |
still be unique.
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
<item>
|
|
Packit |
1470ea |
All methods of a class should also be prefixed with the class name.
|
|
Packit |
1470ea |
</item>
|
|
Packit |
1470ea |
</list>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Additionally, public headers should be included from a subdirectory,
|
|
Packit |
1470ea |
effectively namespacing the header files. For example, instead of
|
|
Packit |
1470ea |
#include <abc.h> , a project should allow its users to
|
|
Packit |
1470ea |
use #include <namespace/abc.h> .
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
Some projects namespace their headers within this subdirectory — for
|
|
Packit |
1470ea |
example, #include <namespace/ns-abc.h> instead of
|
|
Packit |
1470ea |
#include <namespace/abc.h> . This is redundant, but
|
|
Packit |
1470ea |
harmless.
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
For example, for a project called ‘Walbottle’, the short namespace ‘Wbl’
|
|
Packit |
1470ea |
would be chosen. If it has a ‘schema’ class and a ‘writer’ class, it
|
|
Packit |
1470ea |
would install headers:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<list>
|
|
Packit |
1470ea |
<item><file>$(includedir)/walbottle-$API_MAJOR/walbottle/schema.h</file> </item>
|
|
Packit |
1470ea |
<item><file>$(includedir)/walbottle-$API_MAJOR/walbottle/writer.h</file> </item>
|
|
Packit |
1470ea |
</list>
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
(The use of $API_MAJOR above is for
|
|
Packit |
1470ea |
<link xref="parallel-installability">parallel installability</link>.)
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
For the schema class, the following symbols would be exported (amongst
|
|
Packit |
1470ea |
others), following GObject conventions:
|
|
Packit |
1470ea |
|
|
Packit |
1470ea |
<list>
|
|
Packit |
1470ea |
<item>Δομή WblSchema </item>
|
|
Packit |
1470ea |
<item>Δομή WblSchemaClass </item>
|
|
Packit |
1470ea |
<item>Μακροεντολή WBL_TYPE_SCHEMA </item>
|
|
Packit |
1470ea |
<item>Μακροεντολή WBL_IS_SCHEMA </item>
|
|
Packit |
1470ea |
<item>Συνάρτηση wbl_schema_get_type </item>
|
|
Packit |
1470ea |
<item>Συνάρτηση wbl_schema_new </item>
|
|
Packit |
1470ea |
<item>Συνάρτηση wbl_schema_load_from_data </item>
|
|
Packit |
1470ea |
</list>
|
|
Packit |
1470ea |
</section>
|
|
Packit |
1470ea |
</page>
|