IPOL reviews, uses, publishes and distributes some software provided by the authors. With the requirements and recommendations expressed in these guidelines, we intend to facilitate the production and review of verifiable and usable software for reproducible research.
This short list is a summary of the guidelines, to quickly check an IPOL program. The guidelines are detailed and explained later in this document.
name_version.{zip,tar.gz,tgz}
, less than 2 MBname_version/
foldera-z
,A-Z
,0-9
,-
,_
,.
gcc -std=xxx -Wall -Wextra -Werror
libtiff
, libjpeg
, libpng
, zlib
, fftw
, cblas
and clapack
external librariesmake
or cmake
, make
uses $(CC)
or $(CXX)
with only standard optionsREADME.txt
essential informationmain()
and algorithmic code in different filesA web tool to check an IPOL program against some of these guidelines is available with an example of a minimal program following the guidelines at http://tools.ipol.im/pkg/
. This web tool can be used by IPOL authors to verify their code before submission, and by reviewers as a preliminary validation of the software1.
This document is not yet an official IPOL policy. It is a draft, released for comments, corrections and amendments. When a final version is attained, this paragraph will be replaced with the following one:
This document is the official IPOL software guidelines, version XX, published on DD-MM-YYYY. It is immediately applicable and obsoletes previous versions. The reference version is available on line at
http://tools.ipol.im/wiki/ref/software_guidelines/
.
When needed, future versions of this document will be published and replace the current version. The current version will be kept and a summary of the differences will be provided. This will be announced on the IPOL website and the IPOL discussion list.
In this document, the term “IPOL program” is used to designate the reference program implementation of an algorithm submitted for publication in an IPOL article. An IPOL article MAY publish more than one program, an IPOL demo MAY use more than one program.
This document uses the words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL as described in RFC2119, in the context of the IPOL publication process:
No article will be published in IPOL if a program included in this article doesn’t follow such requirements or prohibitions.
The rationale for not following such recommendations MUST be written and agreed by the authors, reviewers and editor before an article is accepted for publication.
An IPOL program MUST be packaged as a compressed archive file. This file archive can either be a single volume .ZIP compressed archive or a GZIP compressed tar archive2. In the remainder of this document, we will use the terms “zip archive” and “tar/gz archive” for convenience.
Annex A. of this document provides some examples of programs that can be used to produce such compressed archives.
The compressed archive file of an IPOL program MUST be named according to the name_version.extension
pattern, where:
name
and version
MUST consist only of lower case letters (a-z
), digits (0-9
), minus (-
) and period (.
) signs;name
MUST be at least two characters long and start with a letter; it MUST indicate the name of the program; this name can be the name of the executable program file, or another name, at the author’s will;version
MUST start with a digit; it MUST indicate a version number for the program, in the sense that two different versions of the program MUST have two different version numbers; if no version numbering scheme is established for the program, the YYYYMMDD
pattern based on the year, month and day of the release date MAY be used;extension
MUST be zip
for zip archives and tar.gz
or tgz
for tar/gz archives.The size of the compressed archive file SHOULD be less than 2 MB.
All the files and folders extracted from the compressed archive MUST be located inside a base folder named name_version
, where name
and version
are identical to those used for the compressed archive file name. Absolute path MUST NOT be used for files and folders extracted from the archive.
The name of all files and folders composing the IPOL program MUST consist only of lower or upper case letters (a-z
, A-Z
), digits (0-9
), minus (-
), underscore (_
) and period (.
) signs. They SHOULD start with a letter.
The names SHOULD provide a meaningful hint of the content of these files and folders.
An IPOL program SHOULD NOT include hidden files or folders or by-products of the tools used by the authors, such as (but not limited to):
.DS_Store
, .directory
);.svn
, .git
);filename~
, filename.bak
).The program SHOULD NOT be distributed with files not useful to build, use or study the implementation of the algorithm published in IPOL.
An IPOL program MUST include all the material necessary to build one or more executable program files implementing the algorithm published in IPOL. This material MUST be provided in human-readable source code form. An IPOL program MUST NOT be distributed with binary pre-compiled files if these files can be obtained from source code3.
Annex B. provides some information for IPOL authors to help them perform various frequent implementation tasks.
The source code of an IPOL program MUST follow the published standard syntax of one or more compiled programming languages. IPOL can currently only process C89 (ANSI C), C99, and C++98 (ISO C++). If the authors want to publish their program with another well-known and standardized compiled language (such as Fortran 90), they should contact the editorial board to investigate the possibilities.
IPOL authors SHOULD test their C and C++ source code with the gcc
compiler in strict compilation mode4 before submitting it to IPOL.
The source code MAY use the OpenMP 3.0 API for shared multiprocessing programming (parallel programming) but it MUST also compile and provide the same results (albeit slower) without OpenMP. Usage of OpenMP MUST NOT be tied to a specific number of processors and MUST only rely on the OpenMP standard, not on any vendor implementation.
The source code of an IPOL program MUST NOT require any extension of the language or its standard library, or any resource specific to a hardware environment, operating system or compiler. These extensions and resources MAY be used to achieve better performances if they are available but their availability MUST be detected during the compilation or execution and an alternative portable implementation MUST be used in their absence. This includes (but is not limited to)
drand48()
);mulps
, __builtin_ia32_mulps()
);GetSystemTime()
, POSIX gettimeofday()
);C:\Documents and Settings
, /tmp
);Special attention will be given to the Linux 64-bit environment because it is currently the primary environment for IPOL demonstrations. But the program MUST also be usable in other environments and this portability MUST NOT be limited to the Win32/POSIX alternative.
An IPOL program MUST not use external software components except for the libraries and APIs listed hereafter; the program MAY expect these software components to be correctly installed and configured during the compilation and execution:
libtiff
version 3.x and libpng
version 1.4.x to read and write files, with their dependencies libjpeg
version 8.x, zlib
version 1.2.x;fftw
version 3.x (single and double precision) for Fourier transforms;cblas
and clapack
for linear algebra.Other libraries can be examined and may be added to this list on request, if they are portable, widely used, with a stable API.
An IPOL program MUST be compiled by an automated non-interactive build procedure with make
or cmake
. This build tool MUST NOT be configured to use any special compiler.
For example, make
MUST NOT call gcc
or g++
but MUST use the $(CC)
and $(CXX)
variables instead. The default build procedure MUST use standard compiler options only5 : -c
, -D
, -E
, -I
, -L
, -l
, -O
, -o
and -U
.
An IPOL program SHOULD be minimal and only perform the algorithm published in IPOL. It MUST be usable from the command line environment without any user interaction, taking all its parameters from the command line.
An IPOL program MUST be able to read the input data and write the final output data in at least one of these standard and documented format: PNG or TIFF raster images, EPS or SVG vector images, PLY or VRML meshes. Other file formats can be added to this list on request, if they are clearly defined and widely used.
Annex B. provides some information for IPOL authors to help them use external libraries to read and write images.
In the demo environment, an IPOL program SHOULD NOT use more than 1 GB of memory and MUST NOT use more than 8 MB of stack memory space (for recursion, local variables and variable-length arrays). The program MUST NOT need more than 30 seconds to process typical data. For slow algorithms, this limit MAY be achieved with parallel processing or a limit on input size.
Annex B. provides some information for IPOL authors to help them improve the performance of their implementation.
Every source code file in an IPOL program MUST mention its authors in a copyright attribution line at the top of the file. This mention MAY be omitted in trivial files such as header code.
Every person whose contribution to this file is not trivial and implies some creative work MUST be credited. Of course, if the authors use and/or modify a file previously written by other persons, the copyright attribution to the previous authors MUST NOT be removed. The copyright attribution MUST include the years of production of the work, the full name and an e-mail address for contributor. It MAY also include other relevant information such as the employer, affiliation or web site.
An simple example for a single author can be:
Copyright (C) 2011, Jane Doe <jane.doe@example.org>
A complex example with many contributors can be:
Copyright (C) 1998-2003, Taro Yamada <taro.yamada@example.jp>
Copyright (C) 2005-2011, Juan Perez <juan.perez@example.es>
Copyright (C) 2011, Marie Untel, ENS Cachan
<marie.untel@ens-cachan.fr>
When the authors are aware or suspect that a source code file implements an algorithm which might be linked to a patent (the main algorithm published on IPOL or another algorithm used for this implementation), a patent warning MUST be inserted after the copyright attribution, in every file potentially linked to this patent. This wording is RECOMMENDED:
This file implements an algorithm possibly linked to the patent
<REFERENCE OF THE PATENT>.
This file is made available for the exclusive aim of serving as
scientific tool to verify the soundness and completeness of the
algorithm description. Compilation, execution and redistribution
of this file may violate patents rights in certain countries.
The situation being different for every country and changing
over time, it is your responsibility to determine which patent
rights restrictions apply to you before you compile, use,
modify, or redistribute this file. A patent lawyer is qualified
to make this determination.
If and only if they don't conflict with any patent terms, you
can benefit from the following license terms attached to this
file.
Every source code file MUST mention a usage and redistribution license after the copyright attribution (and patent warning for algorithms potentially linked to a patent). Of course, if the authors use and/or modify a file previously written by other persons, the license previously mentioned in the file MUST NOT be removed.
These wordings are RECOMMENDED:
This program is free software: you can use, modify and/or
redistribute 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. You should have received a copy of this license along
this program. If not, see <http://www.gnu.org/licenses/>.
This program is free software: you can use, modify and/or
redistribute it under the terms of the simplified BSD
License. You should have received a copy of this license along
this program. If not, see
<http://www.opensource.org/licenses/bsd-license.html>.
This program is provided for research and education only: you can
use and/or modify it for these purposes, but you are not allowed
to redistribute this work or derivative works in source or
executable form. A license must be obtained from the patent right
holders for any other use.
The exact terms can differ, for example when a different GPL/LGPL/AGPL license version is chosen. The full text of the license MUST be included in a separate file with the source code.
IPOL authors SHOULD verify that the usage of these licenses for their software publications complies with their employer policy and local situation and jurisdiction.
Every IPOL program MUST provide a file named README.txt
in the base folder and written in plain text, in English. This README.txt
file MUST include the following essential information, in any order:
This README.txt
file MAY contain other information, and MAY also be completed by another documentation, possibly with more details, in text, PDF, HTML or any other format.
For a simple code, the license information in README.txt
can be
This program is written by Jane Doe <jane.doe@example.org> and
distributed under the terms of the GPLv3 license.
A complex case (multiple authors, patents and licenses) can be:
This program is written by Taro Yamada <taro.yamada@example.jp>
and Juan Perez <juan.perez@example.es> with contributions from
Marie Untel, ENS Cachan <marie.untel@ens-cachan.fr>.
- mmatch.c and rot_tree.c may be linked to the pending EU patent
123.456 by Taro Yamada and Juan Perez and are provided for
scientific and education only.
- demoz.c may be linked to the US patent 65.43.21 by Jane Doe;
see the file for license terms.
- eizo.c and linalg_lib.c are distributed under the terms
of the BSD license.
- All the other files are distributed under the terms of the
LGPLv3 license.
In an IPOL program, the source code is a primary material for the publication. It will be reviewed, published and read like any other part of the article. The authors MUST take care of the clarity of their program.
The source code of an IPOL program MUST be written in English, including all variables, functions names and comments. It MUST be consistently indented and spaced. Lines SHOULD be limited to 80 characters and SHOULD NOT end with blank characters (spaces, tabs, …). Files SHOULD NOT have more than 1000 lines. The line terminations SHOULD be the same (DOS/Windows CR+LF style or UNIX CR style) for all the files of the program.
Functions SHOULD be grouped by abstraction level in different source code files:
main()
function, command-line processing and input/output calls in one file,Annex C. provides some examples of programs that can be used to improve the indentation, spacing and presentation of a source code.
The source code of an IPOL program MUST be commented precisely and exhaustively. Authors SHOULD target the “1/8 comment/instruction ratio”, but the quality of the comments is more important than the quantity.
Authors MUST ensure that the code is understandable, to the satisfaction of the editor and reviewers, so that consistency between the description of the algorithm and its implementation can be verified. The correspondence between each part of the implementation and the respective part of the description of the algorithm MUST be explained in the comments.
Authors SHOULD apply simpler implementations when they are available, follow the conventions of the programming language, and use comments to explain implementation choices and every complicated or subtle point in the program. Clarity is more important than virtuosity.
Every function MUST be documented with at least one line explaining what the function is doing, and the meaning of its parameters and return value.
The Doxygen source code documentation format is RECOMMENDED for every IPOL Program.
Annex C. provides some examples of programs that can be used to count the comment, instruction and blank lines.
The authors SHOULD provide an example of input file to test the IPOL program and the result to expect when this input file is processed by the program.
The annexes are not part of the guidelines. They are provided to help authors and editors follow the guidelines.
IPOL authors can consider that the files produced by the following tools comply with the file format requirements for zip and tar/gz archives:
tar
(usually “GNU tar”), zip
(usually “Info-Zip zip”) and gzip
programs;tar
(usually “BSD tar”) and gzip
programs;7-zip
program.Some help to read and write image files is provided in the IPOL wiki with simplified interfaces to libpng
and libtiff
and some examples. IPOL authors can also find in this wiki a list of contributions and tools from IPOL authors willing to share. They can also reuse code fragments from other published algorithms.
The IPOL editorial board can provide some help to the authors to accelerate their code and guide them for performance profiling and parallel programming. The IPOL discussion list is the good place for any questions related to IPOL, including the implementation work.
IPOL authors can use these programs to improve the presentation and clarity of their source code:
indent
is a C code cleanup tool available on Linux;uncrustify
can also beautify C and C++ code, and is available for Linux and Windows;astyle
can process C and C++ code, and is available for Linux, Mac OS X and Windows;UniversalIndentGUI
is a cross-platform graphical configuration file editor for many code cleanup tools.Tools like cloc
, ohcount
and sloccount
can be used to count the comments, instructions and blank lines and evaluate the comment/instruction ratio.
The absence of error reported by this tool doesn’t imply that all the guidelines are correctly followed. Some guidelines need a human review. ↩
These file formats are defined by the PKZIP APPNOTE specification, version 6.3.2, for the .ZIP compressed archive format, the RFC1952 for the GZIP compressed format, and the POSIX.1 ustar definition for the tar archive format. ↩
If the authors want to distribute binary versions, they can do it in IPOL but not via the compressed archive of the IPOL program. ↩
C89, C99 and C++98 code can be tested with gcc -std=xxx -Wall -Wextra -Werror
where xxx is c89
, c99
or c++98
. ↩
Standard compiler options are defined by the POSIX c99 specification. Other options depending on the environment (hardware, operating system, compiler) MAY also be provided, for example for an optimized compilation, but they MUST NOT be used in the default build procedure. ↩
Distribution “for research and education” can help avoid conflicts between program distribution and patent rights when the patent inventors are the source code authors. It is not needed in other situations because the validity of the license will depend on the local patent regulations, as stated in the last sentence of the patent warning. ↩