Commit 5f5c4e12 authored by Vivien Kraus's avatar Vivien Kraus
Browse files

Freshen up the implementation / docs

parent 6303279d
Pipeline #66006 passed with stage
in 2 minutes and 12 seconds
......@@ -22,4 +22,24 @@
(eval
. (setq company-clang-arguments
(split-string
"-I@abs_top_srcdir@ -I@abs_top_builddir@ @CFLAGS@ @CPPFLAGS@ @ASAN_CFLAGS@ -I@abs_top_srcdir@/src -I@abs_top_builddir@/src -I@abs_top_srcdir@/src/core -I@abs_top_builddir@/src/core -I@abs_top_srcdir@/src/guile -I@abs_top_builddir@/src/guile -I@abs_top_srcdir@/src/guile -I@abs_top_builddir@/src/guile @GUILE_2_0_CFLAGS@ -I@abs_top_srcdir@/src/scm -I@abs_top_builddir@/src/scm ")))))
"
-I@abs_top_srcdir@
-I@abs_top_builddir@
@CFLAGS@
@libunistring_CFLAGS@
@CODE_COVERAGE_CFLAGS@
@CPPFLAGS@
@ASAN_CFLAGS@
-I@abs_top_srcdir@/src
-I@abs_top_builddir@/src
-I@abs_top_srcdir@/src/core
-I@abs_top_builddir@/src/core
-I@abs_top_srcdir@/src/cards
-I@abs_top_builddir@/src/cards
-I@abs_top_srcdir@/src/command
-I@abs_top_builddir@/src/command
-I@abs_top_srcdir@/src/lexer
-I@abs_top_builddir@/src/lexer
-I@abs_top_srcdir@/src/parser
-I@abs_top_builddir@/src/parser
"))))
......@@ -16,6 +16,8 @@
# along with this program. If not, see
# <http://www.gnu.org/licenses/>.
!m4/ax_code_coverage.m4
#*#
*.a
*.dirstamp
*.gcda
......@@ -29,6 +31,7 @@
*.lo
*.log
*.o
*.t2p
*.trs
*~
.deps
......@@ -56,13 +59,15 @@ configure
depcomp
doc/tarot.html
doc/tarot.info
doc/tarot.org
doc/tarot.pdf
doc/tarot.texi
games/*.c
install-sh
lib
libtool
ltmain.sh
m4
!m4/ax_code_coverage.m4
mdate-sh
missing
po/Makefile.in.in
......@@ -82,6 +87,11 @@ public
site.bak
site.exp
src/.dirstamp
src/cards/cards.c
src/cards/check-cards
src/cards/tarot.c
src/cards/tarot.l
src/command/check-command
src/core/check_bid
src/core/check_card_set
src/core/check_composition
......@@ -90,20 +100,24 @@ src/core/check_do_deal
src/core/check_game_init
src/gettext.h
src/guile/libtarot-guile.pc
src/lexer/check-lexer
src/lexer/tarot.c
src/liblibtarot.la
src/libtarot.pc
src/parser/check-parser
src/parser/tarot.c
src/scm/tarot
src/scm/tarot-resource-compiler
src/status/check
stamp-h1
stamp-vti
tarot-*.tar.gz
tarot-devel
tarot-devel-coverage
tarot-*.tar.gz
tarot.log
tarot.sum
tarot.test
test-driver
test-suite.log
texinfo.tex
version.texi
version.texi
\ No newline at end of file
......@@ -3,6 +3,7 @@ image: tarotbis/build:latest
before_script:
- apt-get update
- apt-get upgrade -y
- apt-get install -y --no-install-recommends texlive-base texlive-latex-base git ca-certificates texlive-fonts-recommended texlive-generic-recommended autoconf automake gettext autopoint libtool texinfo gnulib autoconf-archive gobject-introspection make gcc valac valac-vapi gtk-doc-tools flex bison gperf nettle-dev libgtk-3-dev libgirepository1.0-dev emacs org-mode indent doxygen graphviz lcov dejagnu check libxml2-utils xsltproc wget
stages:
- deploy
......@@ -12,4 +13,5 @@ pages:
script: "./deploy.sh"
artifacts:
paths:
- public
\ No newline at end of file
- public
expire_in: 1 week
\ No newline at end of file
FROM debian:stable
RUN apt-get update
RUN apt-get install -y --no-install-recommends texlive-base texlive-latex-base git ca-certificates texlive-fonts-recommended texlive-generic-recommended
RUN apt-get install -y --no-install-recommends autoconf automake gettext autopoint libtool texinfo gnulib autoconf-archive gobject-introspection
RUN apt-get install -y --no-install-recommends make gcc valac valac-vapi gtk-doc-tools flex bison
RUN apt-get install -y --no-install-recommends nettle-dev libgtk-3-dev libgirepository1.0-dev
RUN apt-get install -y --no-install-recommends emacs org-mode indent doxygen graphviz lcov dejagnu check
RUN apt-get install -y --no-install-recommends libxml2-utils xsltproc
RUN apt-get install -y --no-install-recommends guile-2.0-dev
RUN apt-get install -y --no-install-recommends wget
RUN apt-get install -y --no-install-recommends texlive-base texlive-latex-base git ca-certificates texlive-fonts-recommended texlive-generic-recommended autoconf automake gettext autopoint libtool texinfo gnulib autoconf-archive gobject-introspection make gcc valac valac-vapi gtk-doc-tools flex bison gperf nettle-dev libgtk-3-dev libgirepository1.0-dev emacs org-mode indent doxygen graphviz lcov dejagnu check libxml2-utils xsltproc wget
RUN apt-get upgrade -y
MAINTAINER framagit.org/gugurumbe/tarot
\ No newline at end of file
......@@ -19,6 +19,7 @@
SUBDIRS = po
AUTOMAKE_OPTIONS = subdir-objects
bin_PROGRAMS =
bin_SCRIPTS =
dist_bin_SCRIPTS =
lib_LTLIBRARIES =
noinst_LTLIBRARIES =
......@@ -27,12 +28,15 @@ check_PROGRAMS =
info_TEXINFOS =
pkgconfigdir = $(datadir)/pkgconfig
pkgconfig_DATA =
pkgdatadir = $(datadir)/@PACKAGE@
pkgdata_SCRIPTS =
INDENTED =
SUFFIXES =
dist_noinst_SCRIPTS = \
autogen.sh \
.git/hooks/pre-commit \
hooks/pre-commit.sh
nodist_noinst_DATA =
ACLOCAL_AMFLAGS = -I m4 -I custom-m4
EXTRA_DIST = \
......@@ -46,11 +50,14 @@ EXTRA_DIST = \
.dir-locals.el.in \
.gitlab-ci.yml \
Dockerfile
BUILT_SOURCES =
AM_DISTCHECK_CONFIGURE_FLAGS = \
--enable-asan=yes \
--enable-silent-rules=yes \
--disable-code-coverage
AM_CPPFLAGS = -DLOCALEDIR="\"$(localedir)\""
--disable-code-coverage \
--disable-gperf \
--disable-flex
AM_CPPFLAGS = -DLOCALEDIR="\"$(localedir)\"" -I. -I$(srcdir)
AM_CFLAGS =
AM_YFLAGS = -d
AM_LIBS =
......@@ -58,18 +65,23 @@ AM_LDADD =
# Texinfo -> html flags, overriden in doc/Makefile.am
AM_MAKEINFOHTMLFLAGS =
CLEANFILES =
TESTS =
AM_TESTS_ENVIRONMENT = $(LIBTOOL) --mode=execute
if HAVE_VALGRIND
AM_TESTS_ENVIRONMENT += $(VALGRIND) --tool=memcheck
endif # HAVE_VALGRIND
include doc/Makefile.am
include src/Makefile.am
include games/Makefile.am
TESTS = $(check_PROGRAMS)
TESTS += $(check_PROGRAMS)
indent_verbose = $(indent_verbose_@AM_V@)
indent_verbose_ = $(indent_verbose_@AM_DEFAULT_V@)
indent_verbose_0 = @echo " INDENT ";
.PHONY: indent
indent: $(INDENTED)
$(indent_verbose) $(INDENT) $(INDENTED)
$(indent_verbose) (cd $(srcdir) \
&& for file in $(INDENTED); do $(INDENT) $$file; done)
org_verbose = $(org_verbose_@AM_V@)
org_verbose_ = $(org_verbose_@AM_DEFAULT_V@)
org_verbose_0 = @echo "ORG-EXPORT $@";
......@@ -103,13 +115,5 @@ githook_setup_verbose_0 = @echo "ORG-EXPORT $@";
(cp $(srcdir)/hooks/pre-commit.sh \
$(srcdir)/.git/hooks/pre-commit \
&& chmod ugo+x $(srcdir)/.git/hooks/pre-commit)
SUFFIXES += .tarot
trc_verbose = $(trc_verbose_@AM_V@)
trc_verbose_ = $(trc_verbose_@AM_DEFAULT_V@)
trc_verbose_0 = @echo " RESOURCE $<";
.tarot.c:
$(trc_verbose) $(TAROT_RESOURCE_COMPILER) \
-n "_tarot_load_$$(basename -s .tarot $<)" \
$< \
-o $@
@CODE_COVERAGE_RULES@
......@@ -14,19 +14,10 @@ _________________
3 Project site
4 Compile this project
.. 4.1 Gitlab users: make a source distribution
..... 4.1.1 Insane Tooling
..... 4.1.2 The git pre-commit hook
..... 4.1.1 The git pre-commit hook
..... 4.1.2 The CI/CD pipeline
.. 4.2 Everyone: configure, make and install
5 Let me know
6 FAQ
.. 6.1 Emacs? Are you serious?
7 Things to do [0/9]
.. 7.1 TODO Make a great GUI app :-)
.. 7.2 TODO Document the scheme functions
.. 7.3 TODO Restore imputation
.. 7.4 TODO Get rid of doxygen and enable gtk-doc
.. 7.5 TODO Re-implement the tarot-status utility, with a real command line
.. 7.6 TODO Make a great guile app
......@@ -35,7 +26,7 @@ _________________
1 READ ME
=========
RUN THE CONFIGURE SCRIPT NOT THE BOOTSTRAP ONE. If you don't have a
RUN THE CONFIGURE SCRIPT NOT `autogen.sh'. If you don't have a
configure script, see section 4.1.
......@@ -80,56 +71,26 @@ http://gugurumbe.frama.io/tarot/coverage/index.html
You need more tools in order to bootstrap the source distribution.
I am assuming you run on debian stable, if you don't then please tell
me. If you work on a platform where the extensive tooling described
in section 4.1.1 is /not/ available, or difficult to install, then I
advise you to make a /source/ distribution from an easier system or
download [the latest build on the "develop" branch], and then use this
distribution as discussed in section 4.2.
If you still want to re-build the source distribution, and you are not
on a debian stable system, then be aware that the `bootstrap.sh'
script will try to import `gettext.h' from
`/usr/share/gettext/gettext.h'. If those files are packaged in
another place, then you either have to make a symlink or edit the
`xslt/Makefile.am.xslt' script and tell me where you found those
files.
[the latest build on the "develop" branch]
http://gugurumbe.frama.io/tarot/tarot-devel.tar.gz
4.1.1 Insane Tooling
--------------------
You have to install the autotools (`autoconf', `automake', `libtool',
`texinfo' and `autoreconf'), an XSLT processor (`xsltproc'), a XML
linter (`xmllinnt'), and optionally `indent' (very recommended),
`emacs' (if you edit this README) and `docker' (if you want to
re-build the `tarotbis/build:latest' docker image yourself). Once
this is done, you can run at the top-level directory:
,----
| make -f Makefile.bootstrap
`----
me. If you work on a platform where the a tool required to make a
distribution, such as emacs with a recent enough version of org-mode
is /not/ available, or difficult to install, then I advise you to make
a /source/ distribution from an easier system or download [the build
from the latest passing commit], and then use this distribution as
discussed in section 4.2.
It will:
- take files from your system, namely `gettext.h' and put it in the
sources;
- set up the autotools build system from build.xml;
- run autoreconf;
- install a (severe) `git' pre-commit hook.
[the build from the latest passing commit]
http://gugurumbe.frama.io/tarot/tarot-devel.tar.gz
4.1.2 The git pre-commit hook
4.1.1 The git pre-commit hook
-----------------------------
The pre-commit hook checks quite thoroughly that the changes you made
and commited:
- build on debian stable from scratch (like what you are doing right
now);
- build from scratch (like what you are doing right now);
- pass the unit and program tests;
- pass the distcheck test without the extensive tooling (like what you
would be doing if you did not choose to rebuild the source
- pass the distcheck test without touching the distributed files (like
what you would be doing if you did not choose to rebuild the source
distribution);
- are correctly indented with GNU indent;
- are not altered by any build step (except for the `po' files which
......@@ -139,7 +100,23 @@ http://gugurumbe.frama.io/tarot/tarot-devel.tar.gz
This operation is time-consuming, but you can bypass it by disabling
the hook during the git commit. However you should pass this hook for
every commit on the `develop' and `master' branches to help maintain
the project.
the project. And if you disable the hook, then the CI pipeline is
very likely to fail anyways.
4.1.2 The CI/CD pipeline
------------------------
Once you push your commit, the CI/CD settings in `gitlab-ci.yml' will
rebuild a distribution from scratch, and upload some interesting files
like the HTML / PDF versions of the manual, the coverage report, and
the distribution. If you need fancier tools to build (e.g. you want
to automatically screencast the program under the control of a script
and distribute the video, or whatever), then make sure that the tools
to do that are available on debian and are installed both by the
Dockerfile and `.gitlab-ci.yml'.
I already have bison, flex and gperf, and emacs, in that category.
4.2 Everyone: configure, make and install
......@@ -153,25 +130,9 @@ http://gugurumbe.frama.io/tarot/tarot-devel.tar.gz
to know what options are available. If you want more details, see
`INSTALL'.
There are two dependencies: `guile', and `readline'. `guile' is easy,
it should be found as a pkg-config module. If it is not, then you
will want to explicitely set the compiler and linker flags:
,----
| ./configure \
| GUILE_2_0_CFLAGS="$(guile-config compile)" \
| GUILE_2_0_LIBS="$(guile-config link)"
`----
`readline' is a little more problematic, since it does not distribute
a pkg-config description at all. So you have to guess. On debian
stable, this should work:
,----
| ./configure \
| GUILE_2_0_CFLAGS="$(guile-config compile)" \
| GUILE_2_0_LIBS="$(guile-config link)" \
| READLINE_CFLAGS="-I/usr/include" \
| READLINE_LIBS="-lreadline"
`----
There are some dependencies, some optional, some are known not to have
a pkg-config configuration. In this case, pass the compiler flags and
linker flags as instructed at the end of `./configure --help'.
5 Let me know
......@@ -179,54 +140,3 @@ http://gugurumbe.frama.io/tarot/tarot-devel.tar.gz
I develop Tarot as a personal hobby. If you find it interesting, or
have bugs to submit, please let me know: `vivien@planete-kraus.eu'
6 FAQ
=====
6.1 Emacs? Are you serious?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Org-mode is a fantastic program. If you want to modify this README,
you have to have emacs installed.
7 Things to do [0/9]
====================
7.1 TODO Make a great GUI app :-)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7.2 TODO Document the scheme functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The game loader, mainly. The compiler is irrelevant but should be at
least hinted in the manual.
7.3 TODO Restore imputation
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The imputation should be in an auxiliary module, and should be updated
independently of the game.
7.4 TODO Get rid of doxygen and enable gtk-doc
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We /need/ gtk-doc to have the gobject introspection right. I suggest
we simply drop Doxygen, not to duplicate the API documentation.
7.5 TODO Re-implement the tarot-status utility, with a real command line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Don't use bison for this, because:
- it has to load the entire game in memory, and cannot process
commands individually;
- it will not be possible to support readline auto-completion.
7.6 TODO Make a great guile app
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#orgf0c678e">1. READ ME</a></li>
<li><a href="#org66246c1">2. About tarot</a></li>
<li><a href="#org764b6a7">3. Project site</a></li>
<li><a href="#org9ab8fe2">4. Compile this project</a>
<ul>
<li><a href="#org88ba06b">4.1. Gitlab users: make a source distribution</a>
<ul>
<li><a href="#org746704c">4.1.1. Insane Tooling</a></li>
<li><a href="#org072715d">4.1.2. The git pre-commit hook</a></li>
</ul>
</li>
<li><a href="#org5d24165">4.2. Everyone: configure, make and install</a></li>
</ul>
</li>
<li><a href="#orgb500ff7">5. Let me know</a></li>
<li><a href="#org140dc84">6. FAQ</a>
<ul>
<li><a href="#org4bb9972">6.1. Emacs? Are you serious?</a></li>
</ul>
</li>
<li><a href="#org24334cd">7. Things to do <code>[0/9]</code></a>
<ul>
<li><a href="#org69e8241">7.1. <span class="todo TODO">TODO</span> Make a great GUI app :-)</a></li>
<li><a href="#org755cad6">7.2. <span class="todo TODO">TODO</span> Document the scheme functions</a></li>
<li><a href="#org5541aa3">7.3. <span class="todo TODO">TODO</span> Restore imputation</a></li>
<li><a href="#org21d684c">7.4. <span class="todo TODO">TODO</span> Get rid of doxygen and enable gtk-doc</a></li>
<li><a href="#org38b881f">7.5. <span class="todo TODO">TODO</span> Re-implement the tarot-status utility, with a real command line</a></li>
<li><a href="#org3185892">7.6. <span class="todo TODO">TODO</span> Make a great guile app</a></li>
</ul>
</li>
</ul>
</div>
</div>
<a id="orgf0c678e"></a>
# Table of Contents
1. [READ ME](#org7a2beec)
2. [About tarot](#org7af94e6)
3. [Project site](#org3f643fb)
4. [Compile this project](#orgdb94484)
1. [Gitlab users: make a source distribution](#org274450d)
1. [The git pre-commit hook](#org34778df)
2. [The CI/CD pipeline](#org9402a70)
2. [Everyone: configure, make and install](#org6e132d9)
5. [Let me know](#org629d015)
<a id="org7a2beec"></a>
# READ ME
RUN THE CONFIGURE SCRIPT NOT THE BOOTSTRAP ONE. If you don't have a
configure script, see section [4.1](#org88ba06b).
RUN THE CONFIGURE SCRIPT NOT `autogen.sh`. If you don't have a
configure script, see section [4.1](#org274450d).
<a id="org66246c1"></a>
<a id="org7af94e6"></a>
# About tarot
......@@ -54,14 +30,14 @@ Of Tarot*. It aims at providing a game and an artificial
intelligence.
<a id="org764b6a7"></a>
<a id="org3f643fb"></a>
# Project site
Go check out the [project manual](http://gugurumbe.frama.io/tarot/share/doc/tarot/tarot.html/index.html) and the [project code coverage report](http://gugurumbe.frama.io/tarot/coverage/index.html).
<a id="org9ab8fe2"></a>
<a id="orgdb94484"></a>
# Compile this project
......@@ -73,62 +49,32 @@ some more work. Note that a source distribution is already available
my autotools!).
<a id="org88ba06b"></a>
<a id="org274450d"></a>
## Gitlab users: make a source distribution
You need more tools in order to bootstrap the source distribution.
I am assuming you run on debian stable, if you don't then please tell
me. If you work on a platform where the extensive tooling described
in section [4.1.1](#org746704c) is *not* available, or difficult to install,
then I advise you to make a *source* distribution from an easier
system or download [the latest build on the "develop" branch](http://gugurumbe.frama.io/tarot/tarot-devel.tar.gz), and then
use this distribution as discussed in section [4.2](#org5d24165).
If you still want to re-build the source distribution, and you are not
on a debian stable system, then be aware that the `bootstrap.sh`
script will try to import `gettext.h` from
`/usr/share/gettext/gettext.h`. If those files are packaged in
another place, then you either have to make a symlink or edit the
`xslt/Makefile.am.xslt` script and tell me where you found those
files.
me. If you work on a platform where the a tool required to make a
distribution, such as emacs with a recent enough version of org-mode
is *not* available, or difficult to install, then I advise you to make
a *source* distribution from an easier system or download [the build
from the latest passing commit](http://gugurumbe.frama.io/tarot/tarot-devel.tar.gz), and then use this distribution as
discussed in section [4.2](#org6e132d9).
<a id="org746704c"></a>
### Insane Tooling
You have to install the autotools (`autoconf`, `automake`, `libtool`,
`texinfo` and `autoreconf`), an XSLT processor (`xsltproc`), a XML
linter (`xmllinnt`), and optionally `indent` (very recommended),
`emacs` (if you edit this README) and `docker` (if you want to
re-build the `tarotbis/build:latest` docker image yourself). Once
this is done, you can run at the top-level directory:
make -f Makefile.bootstrap
It will:
- take files from your system, namely `gettext.h` and put it in the
sources;
- set up the autotools build system from build.xml;
- run autoreconf;
- install a (severe) `git` pre-commit hook.
<a id="org072715d"></a>
<a id="org34778df"></a>
### The git pre-commit hook
The pre-commit hook checks quite thoroughly that the changes you made
and commited:
- build on debian stable from scratch (like what you are doing right
now);
- build from scratch (like what you are doing right now);
- pass the unit and program tests;
- pass the distcheck test without the extensive tooling (like what you
would be doing if you did not choose to rebuild the source
- pass the distcheck test without touching the distributed files (like
what you would be doing if you did not choose to rebuild the source
distribution);
- are correctly indented with GNU indent;
- are not altered by any build step (except for the `po` files which
......@@ -138,10 +84,27 @@ and commited:
This operation is time-consuming, but you can bypass it by disabling
the hook during the git commit. However you should pass this hook for
every commit on the `develop` and `master` branches to help maintain
the project.
the project. And if you disable the hook, then the CI pipeline is
very likely to fail anyways.
<a id="org9402a70"></a>
<a id="org5d24165"></a>
### The CI/CD pipeline
Once you push your commit, the CI/CD settings in `gitlab-ci.yml` will
rebuild a distribution from scratch, and upload some interesting files
like the HTML / PDF versions of the manual, the coverage report, and
the distribution. If you need fancier tools to build (e.g. you want
to automatically screencast the program under the control of a script
and distribute the video, or whatever), then make sure that the tools
to do that are available on debian and are installed both by the
Dockerfile and `.gitlab-ci.yml`.
I already have bison, flex and gperf, and emacs, in that category.
<a id="org6e132d9"></a>
## Everyone: configure, make and install
......@@ -152,92 +115,15 @@ You can run:
to know what options are available. If you want more details, see
`INSTALL`.
There are two dependencies: `guile`, and `readline`. `guile` is easy,
it should be found as a pkg-config module. If it is not, then you
will want to explicitely set the compiler and linker flags:
./configure \
GUILE_2_0_CFLAGS="$(guile-config compile)" \
GUILE_2_0_LIBS="$(guile-config link)"
`readline` is a little more problematic, since it does not distribute
a pkg-config description at all. So you have to guess. On debian
stable, this should work:
./configure \
GUILE_2_0_CFLAGS="$(guile-config compile)" \
GUILE_2_0_LIBS="$(guile-config link)" \
READLINE_CFLAGS="-I/usr/include" \
READLINE_LIBS="-lreadline"
There are some dependencies, some optional, some are known not to have
a pkg-config configuration. In this case, pass the compiler flags and
linker flags as instructed at the end of `./configure --help`.
<a id="orgb500ff7"></a>
<a id="org629d015"></a>
# Let me know
I develop Tarot as a personal hobby. If you find it interesting, or
have bugs to submit, please let me know: `vivien@planete-kraus.eu`
<a id="org140dc84"></a>
# FAQ
<a id="org4bb9972"></a>
## Emacs? Are you serious?
Org-mode is a fantastic program. If you want to modify this README,
you have to have emacs installed.
<a id="org24334cd"></a>
# Things to do <code>[0/9]</code>
<a id="org69e8241"></a>
## Make a great GUI app :-)