Skip to content
Commits on Source (62)
Questions to:
Gnome Keyring Mailing List <gnome-keyring-list@gnome.org>
Main authors:
Stef Walter <stefw@collabora.co.uk>
Contributing to GCR, GCK libraries
==================================
Code merging
------------
This is the work flow for modifying the gcr repository:
1. File a bug for the given flaw or feature (if it does not already exist) at
https://gitlab.gnome.org/GNOME/gcr/issues.
2. Create a fork of the main repository on gitlab.gnome.org (if you haven't
already) and commit your work there.
3. If this is a non-trivial flaw or feature, write test cases. We won't accept
significant changes without adequate test coverage.
4. Write code to fix the flaw or add the feature. In the case that tests are
necessary, the new tests must pass consistently.
5. All code must follow the project coding style (see below).
6. Make a Merge Request from your fork to the main gcr repository.
7. The project must remain buildable with all meson options and pass all
tests on all platforms. It should also pass the CI.
8. Rework your code based on suggestions in the review and submit new patches.
Return to the review step as necessary.
9. Finally, if everything is reviewed and approved, a maintainer will merge it
for you. Thanks!
Repository Structure
--------------------
* egg: Various bits of code shared with other modules (private)
* gck: A public library for accessing PKCS#11 modules.
* gcr: A public library for bits of crypto and parsing etc...
* ui: A public library that provides a GTK UI for several objects in gcr.
* schema: Desktop settings schemas for crypto stuff
* testing: Testing CA, gnupg and other mock setups
* po: Contains translation files
Coding style
------------
Our coding style is very similar to the linux coding style:
http://lxr.linux.no/linux/Documentation/CodingStyle
+ Space between function name and parentheses.
```
my_function_call (arg1, arg2);
```
* Braces on the same line as conditional with spaces around braces:
```
if (test) {
do_y ();
do_z ();
}
switch (value) {
case CONSTANT:
do_z ();
break;
default:
break;
}
```
* Braces around functions on a separate line from function name,
return value on a separate line, arguments on separate lines.
```
static void
my_special_function (int arg1,
int arg2)
{
/* body of function */
}
```
* Don't use braces unnecessarily:
```
if (test)
do_this_thing ();
```
* But use braces here, when one section has more than a line:
```
if (test) {
do_this_thing ();
} else {
do_other_thing ();
smile_nicely ();
}
```
* Use of tabs for 8 char indent.
```
------->if (test) {
------->------->Value;
------->------->Value;
------->}
```
* No trailing whitespace on lines.
* The '*' in a pointer declaration belongs with the variable name:
```
char *name;
```
+ Extra long wrapped lines should wrap to function opening brace
using spaces past indentation point.
```
------>my_function_call ("this is a very long argument here",
------> "wrapped argument is indented with spaces");
```
* Function names are in lower case with _ separators.
```
this_is_a_long_function_name ();
```
* Constants are all in upper case with _ separators.
```
THIS_IS_A_CONSTANT
```
+ Structures should be typedefed to avoid saying 'struct' and names
are CamelCase:
```
ThisIsAStruct
```
* One line comments should look like:
```
/* This is a one line comment */
```
* Multi line comments should look like:
```
/*
* This is a multiline comment.
* And it has a useless second line.
*/
```
When in doubt, adapt to the style of the code around your patch.
=== ChangeLog discontinued ===
gcr does not use a manually edited ChangeLog file. We rely on commit
messages to provide change history. Please write commit messages
in the following format:
=== begin example commit ===
Short explanation of the commit
Longer explanation explaining exactly what's changed, whether any
external or private interfaces changed, what bugs were fixed (with bug
tracker reference if applicable) and so forth. Be concise but not too
brief.
=== end example commit ===
- Always add a brief description of the commit to the _first_ line of
the commit and terminate by two newlines. This may be the title of
a fixed bug, copied from Bugzilla.
- First line (the brief description) must only be one sentence and
should start with a capital letter unless it starts with a
lowercase symbol or identifier. Don't use a trailing full stop,
and don't exceed 72 characters.
- The main description (the body) is normal prose and should use
normal punctuation and capital letters where appropriate.
- When committing code on behalf of others use the --author option,
e.g. git commit -a --author "Joe Coder <joe@coder.org>" and
--signoff.
HACKING GCR and GCK libraries
BUILD OPTIONS
---------------
Build options for developers:
--enable-strict: Build with -Werror, disable deprecations, and fatal warnings
--enable-debug: Turn off compiler optimization
--disable-debug: Turn off all debug options and output.
--enable-coverage: Build coverage, use 'make coverage' for summary.
PATCHES
----------
Patches should be submitted to bugzilla:
http://bugzilla.gnome.org/enter_bug.cgi?product=gnome-keyring&component=gcr
The gnome-keyring mailing list is:
gnome-keyring-list@gnome.org
egg
Various bits of code shared with other modules
gck
A public library for accessing PKCS#11 modules.
gcr
A public library for bits of crypto UI and parsing etc...
schema
Desktop settings schemas for crypto stuff
testing
Testing CA, gnupg and other mock setups
----------------------------------------------------------------------------------
CODING STYLE
----------------------------------------------------------------------------------
Our coding style is very similar to the linux coding style:
http://lxr.linux.no/linux/Documentation/CodingStyle
Summary below. Differences from Linux coding style are marked with a plus
instead of an asterisk:
+ Space between function name and parentheses.
my_function_call (arg1, arg2);
* Braces on the same line as conditional with spaces around braces:
if (test) {
do_y ();
do_z ();
}
switch (value) {
case CONSTANT:
do_z ();
break;
default:
break;
}
* Braces around functions on a separate line from function name,
return value on a separate line, arguments on separate lines.
static void
my_special_function (int arg1,
int arg2)
{
/* body of function */
}
* Don't use braces unnecessarily:
if (test)
do_this_thing ();
* But use braces here, when one section has more than a line:
if (test) {
do_this_thing ();
} else {
do_other_thing ();
smile_nicely ();
}
* Use of tabs for 8 char indent.
------->if (test) {
------->------->Value;
------->------->Value;
------->}
* No trailing whitespace on lines. Git will warn you about this.
Please enforce it like so (in gnome-keyring checkout):
$ cp -ipv .git/hooks/pre-commit.sample .git/hooks/pre-commit
* The '*' in a pointer declaraction belongs with the variable name:
char *name;
+ Extra long wrapped lines should wrap to function opening brace
using spaces past indentation point.
------>my_function_call ("this is a very long argument here",
------> "wrapped argument is indented with spaces");
* Function names are in lower case with _ separators.
this_is_a_long_function_name ();
* Constants are all in upper case with _ separators.
THIS_IS_A_CONSTANT
+ Structures should be typedefed to avoid saying 'struct' and names
are CamelCase:
ThisIsAStruct
* One line comments should look like:
/* This is a one line comment */
* Multi line comments should look like:
/*
* This is a multiline comment.
* And it has a useless second line.
*/
When in doubt adapt to the style of the code around your patch.
Stef Walter
E-mail: stefw@collabora.co.uk
Userid: stefw
NULL =
SUBDIRS = \
. \
po \
docs/reference/gck \
docs/reference/gcr
ACLOCAL_AMFLAGS = -I build/m4 ${ACLOCAL_FLAGS}
DISTCHECK_CONFIGURE_FLAGS = \
--enable-gtk-doc \
--disable-coverage \
--disable-update-mime \
--disable-update-icon-cache \
--with-gtk \
--with-pkcs11-modules=$(abs_srcdir)/$(top_distdir)/_inst/lib/
DISTCLEANFILES = \
$(NULL)
dist-hook:
@if test -d "$(srcdir)/.git"; \
then \
echo Creating ChangeLog && \
( cd "$(top_srcdir)" && \
echo '# Generate automatically. Do not edit.'; echo; \
$(top_srcdir)/missing --run git log --stat --date=short ) > ChangeLog.tmp \
&& mv -f ChangeLog.tmp $(top_distdir)/ChangeLog \
|| ( rm -f ChangeLog.tmp ; \
echo Failed to generate ChangeLog >&2 ); \
else \
echo A git clone is required to generate a ChangeLog >&2; \
fi
check-local: check-gck-symbols check-gcr-symbols check-ui-symbols
upload-release: $(DIST_ARCHIVES)
scp $(DIST_ARCHIVES) master.gnome.org:
ssh master.gnome.org ftpadmin install $(DIST_ARCHIVES)
# Default executable tests
LOG_DRIVER = $(srcdir)/build/tap-driver
LOG_DRIVER_FLAGS = --format=tap
LOG_COMPILER = $(srcdir)/build/tap-gtester
VALGRIND_ARGS = --trace-children=no --quiet --error-exitcode=33 \
--suppressions=valgrind-suppressions --gen-suppressions=all \
--num-callers=16
VALGRIND_SUPPRESSIONS = \
build/gcr.supp \
build/gcrypt.supp \
build/glib.supp \
build/glibc.supp \
build/p11-kit.supp \
build/pixman.supp \
build/pthread.supp \
build/unknown.supp
valgrind-suppressions: $(VALGRIND_SUPPRESSIONS)
$(AM_V_GEN) cat $^ > $@
check-memory: valgrind-suppressions
$(MAKE) LOG_FLAGS="-- libtool --mode=execute valgrind $(VALGRIND_ARGS)" \
$(AM_MAKEFLAGS) check
recheck-memory: valgrind-suppressions
$(MAKE) LOG_FLAGS="-- libtool --mode=execute valgrind $(VALGRIND_ARGS)" \
$(AM_MAKEFLAGS) recheck
coverage:
mkdir -p $(top_builddir)/build/coverage
$(LCOV) --directory . --capture --output-file $(top_builddir)/build/coverage.info
$(GENHTML) --output-directory $(top_builddir)/build/coverage $(top_builddir)/build/coverage.info
$(LCOV) --directory . --zerocounters
@echo "file://$(abs_top_builddir)/build/coverage/index.html"
clear-coverage:
$(LCOV) --directory . --zerocounters
AM_CPPFLAGS = \
-I$(srcdir) \
-I$(builddir) \
-I$(srcdir)/build \
-DSRCDIR="\"@abs_srcdir@\"" \
-DBUILDDIR="\"@abs_builddir@\"" \
-DLOCALEDIR=\""$(datadir)/locale"\" \
-DLIBEXECDIR="\"$(libexecdir)\"" \
$(GLIB_CFLAGS)
LDADD = \
$(GLIB_LIBS)
BUILT_SOURCES =
TESTS =
check_PROGRAMS =
check_LTLIBRARIES =
lib_LTLIBRARIES =
libexec_PROGRAMS =
noinst_LTLIBRARIES =
noinst_PROGRAMS = $(check_PROGRAMS)
pkgconfig_DATA =
pkgconfigdir = $(libdir)/pkgconfig
CLEANFILES = \
$(pkgconfig_DATA)
EXTRA_DIST = \
HACKING \
build/valgrind \
$(VALGRIND_SUPPRESSIONS) \
build/enum-template.c \
build/enum-template.h \
build/g-ir-unbreak.xsl \
build/tap-driver \
build/tap-gtester \
build/gdbus-unbreak-codegen \
$(NULL)
TEST_SUPPRESSIONS = $(top_builddir)/build/valgrind-suppressions
GDBUS_CODEGEN = $(top_srcdir)/build/gdbus-unbreak-codegen
V_SED = $(V_SED_$(V))
V_SED_ = $(V_SED_$(AM_DEFAULT_VERBOSITY))
V_SED_0 = @echo " SED " $@;
SED_SUBST = sed \
-e 's,[@]datadir[@],$(datadir),g' \
-e 's,[@]libexecdir[@],$(libexecdir),g' \
-e 's,[@]libdir[@],$(libdir),g' \
-e 's,[@]includedir[@],$(includedir),g' \
-e 's,[@]datarootdir[@],$(datarootdir),g' \
-e 's,[@]sysconfdir[@],$(sysconfdir),g' \
-e 's,[@]bindir[@],$(bindir),g' \
-e 's,[@]exec_prefix[@],$(exec_prefix),g' \
-e 's,[@]prefix[@],$(prefix),g' \
-e 's,[@]PACKAGE[@],$(PACKAGE),g' \
-e 's,[@]VERSION[@],$(VERSION),g' \
$(NULL)
.desktop.in.in.desktop.in:
$(V_SED) $(SED_SUBST) $< > $@
.service.in.service:
$(V_SED) $(SED_SUBST) $< > $@
ENUM_TEMPLATE_C = $(top_srcdir)/build/enum-template.c
ENUM_TEMPLATE_H = $(top_srcdir)/build/enum-template.h
V_XSLTPROC = $(V_XSLTPROC_$(V))
V_XSLTPROC_ = $(V_XSLTPROC_$(AM_DEFAULT_VERBOSITY))
V_XSLTPROC_0 = @echo " XSLTPROC" $@;
FIX_GIR = $(top_srcdir)/build/g-ir-unbreak.xsl
.broken.gir.gir:
$(V_XSLTPROC) xsltproc -o $@ $(FIX_GIR) $<
.broken.typelib.typelib:
$(AM_V_GEN) cp $< $@
SUFFIXES = .desktop.in .desktop.in.in .service .service.in .broken.typelib .broken.gir .gir
if HAVE_INTROSPECTION
include $(INTROSPECTION_MAKEFILE)
INTROSPECTION_GIRS =
INTROSPECTION_SCANNER_ARGS = $(INTROSPECTION_FLAGS) --warn-all --add-include-path=.
INTROSPECTION_COMPILER_ARGS = --includedir=.
girdir = $(datadir)/gir-1.0
gir_DATA =
typelibsdir = $(libdir)/girepository-1.0
typelibs_DATA = $(gir_DATA:.gir=.typelib)
CLEANFILES += \
$(gir_DATA) \
$(typelibs_DATA) \
$(BUILT_SOURCES)
if ENABLE_VAPIGEN
include $(VAPIGEN_MAKEFILE)
VAPIGEN_VAPIS =
VAPI_DEPS = $(VAPIGEN_VAPIS:.vapi=.deps)
vapidir = $(datadir)/vala/vapi
vapi_DATA = $(VAPIGEN_VAPIS) $(VAPI_DEPS)
CLEANFILES += \
$(VAPIGEN_VAPIS) \
$(VAPI_DEPS)
endif
endif
include egg/Makefile.am
include gck/Makefile.am
include gcr/Makefile.am
include schema/Makefile.am
if WITH_GTK
include ui/Makefile.am
include ui/icons/Makefile.am
endif
gcr 3.38.1:
gcr 3.40.0:
- FEATURE: add hkps://keys.openpgp.org to keyserver defaults [GNOME/gcr!62]
- gcr/key-mechanism: Port to GTask [GNOME/gcr!66]
- GckCall: Simplify the code by using GTask based implementation [GNOME/gcr!61]
- Remove Autotools [GNOME/gcr!58]
- gck: Don't use g_assert() in tests [GNOME/gcr!64]
- Create a workaround for tests and GTask [GNOME/gcr!65]
- ui: Set "use-underline" for GcrImportButton [GNOME/gcr!63]
- Updated Chinese (Taiwan) translation
- Get rid of most GSimpleAsyncResult usages [GNOME/gcr!29]
- Gck flags check fixes [GNOME/gcr!60]
- Increase test-gnupg-collection timeout [GNOME/gcr#29, GNOME/gcr!23]
- ci: Fix ASAN jobs [GNOME/gcr!59]
- Updated translations
gcr 3.38.0:
- No changes from 3.37.91
......
GCR is a library for displaying certificates, and crypto UI, accessing
key stores. It also provides the viewer for crypto files on the GNOME
desktop.
GCK is a library for accessing PKCS#11 modules like smart cards, in a
(G)object oriented way.
DEBUG TRACING
==============
The Gcr and Gck libraries contain statements which help debug flow
and logic. In many cases these help you track down problems.
Use the environment variable G_MESSAGES_DEBUG='all' or G_MESSAGES_DEBUG='xxx'
to display either all messages or a specific categories of debug messages. You
can separate categories in this list with spaces, commas or semicolons. Gcr
library uses category 'Gcr', while Gck library uses category 'Gck'.
Example to display all debug messages:
$ G_MESSAGES_DEBUG=all gcr-viewer /path/to/certificate.crt
(gcr-viewer:9418): Gcr-DEBUG: gcr_pkcs11_initialize_async: starting initialize of registered modules
...
Example to display debug messages for a specific category:
$ G_MESSAGES_DEBUG="Gcr" gcr-viewer /path/to/certificate.crt
(gcr-viewer:9503): Gcr-DEBUG: gcr_pkcs11_initialize_async: starting initialize of registered modules
...
For the Gck debug messages simply replace 'Gcr' with 'Gck' in the above
examples.
GCR
===
GCR is a library for displaying certificates and crypto UI, accessing
key stores. It also provides the viewer for crypto files on the GNOME
desktop.
GCK is a library for accessing PKCS#11 modules like smart cards, in a
(G)object oriented way.
Building
--------
You can build GCR using [Meson] with the following build commands (replace
`$BUILDDIR` with your chosed build directory).
```
$ meson $BUILDDIR
$ meson compile -C $BUILDDIR
$ meson install -C $BUILDDIR
```
Contributing
------------
The code and issue tracker of GCR can be found at the GNOME GitLab instance at
https://gitlab.gnome.org/GNOME/gcr.
If you would like to get involved with GNOME projects, please also visit our
[Newcomers page] on the Wiki.
Debug tracing
-------------
The Gcr and Gck libraries contain statements which help debug flow
and logic. In many cases these help you track down problems.
Use the environment variable `G_MESSAGES_DEBUG='all'` or
`G_MESSAGES_DEBUG='xxx'` to display either all messages or a specific categories
of debug messages. You can separate categories in this list with spaces, commas
or semicolons. Gcr library uses category 'Gcr', while Gck library uses category
'Gck'.
```
# Example to display all debug messages:
$ G_MESSAGES_DEBUG=all gcr-viewer /path/to/certificate.crt
# Example to display debug messages for a specific category:
$ G_MESSAGES_DEBUG="Gcr" gcr-viewer /path/to/certificate.crt
```
For the Gck debug messages simply replace 'Gcr' with 'Gck' in the above
examples.
More information
----------------
To discuss issues with developers and other users, you can post to the
[GNOME Discourse instance](https://discourse.gnome.org).
[Meson]: https://mesonbuild.com
[Newcomers page]: https://wiki.gnome.org/TranslationProject/JoiningTranslation
#!/bin/sh
# Run this to generate all the initial makefiles, etc.
test -n "$srcdir" || srcdir=`dirname "$0"`
test -n "$srcdir" || srcdir=.
olddir=`pwd`
cd $srcdir
(test -f configure.ac) || {
echo "*** ERROR: Directory "\`$srcdir\'" does not look like the top-level project directory ***"
exit 1
}
PKG_NAME=`autoconf --trace 'AC_INIT:$1' configure.ac`
if [ "$#" = 0 -a "x$NOCONFIGURE" = "x" ]; then
echo "*** WARNING: I am going to run \`configure' with no arguments." >&2
echo "*** If you wish to pass any to it, please specify them on the" >&2
echo "*** \`$0\' command line." >&2
echo "" >&2
fi
aclocal --install || exit 1
gtkdocize --copy || exit 1
autoreconf --verbose --force --install || exit 1
cd $olddir
if [ "$NOCONFIGURE" = "" ]; then
$srcdir/configure "$@" || exit 1
if [ "$1" = "--help" ]; then
exit 0
else
echo "Now type \`make\' to compile $PKG_NAME" || exit 1
fi
else
echo "Skipping configure process."
fi
# Put a redirect makefile here
if [ ! -f $srcdir/Makefile ]; then
cat $srcdir/build/Makefile.redirect > $srcdir/Makefile
printf "\nREDIRECT = %s\n" "$(realpath $olddir)" >> $srcdir/Makefile
fi