IPOL reviews, uses, publishes and distributes some software provided by the IPOL authors. These guidelines define as a set of requirements and recommendations to ensure the quality of this software and allow automated processing of this software.
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 policy, version XX, published from DD-MM-YYYY. It is immediately applicable and obsoletes previous versions. The reference version is available on line at
http://tools.ipol.im/wiki/xxxx.
When needed, future versions of this document will be published instead of 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 software” is used to designate the reference software implementation of an algorithm submitted for publication in an IPOL article.
This document uses the words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL as described in RFC 2119, in the context of the IPOL publication process:
No article will be published in IPOL if a software 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 software MUST be packaged as a single compressed archive file. This file archive can either be a single volume .ZIP compressed archive or a GZIP compressed tar archive1. Annex A. of this document provides examples of programs that can be used to produce such compressed archives.
In the remainder of this document, we will use the terms “zip archive” and “tar/gz archive” for convenience.
The compressed archive file of an IPOL software 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 software, which MAY not be the name of the executable program provided by this software;version MUST start with a digit; it MUST indicate a version number for the software, in the sense that two different versions of the software MUST have two different version numbers; if no versioning scheme is established for the software, 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 of a software SHOULD be less than 2 MiB.
The content extracted from the compressed archive is a set of files and folders. All this content MUST be located inside a base folder named name_version, where name and version are identical to those used for the archive file name.
Absolute path MUST NOT be used for files and folders extracted from the archive.
File and folder names 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, and they SHOULD NOT be completely in upper case.
The names SHOULD provide a meaningful hint of the content of these files and folders.
An IPOL software MUST NOT include hidden files or artifacts of the tools used by the authors, such as (but not limited to):
.DS_Store, .directory);.svn, CVS);.gitignore);filename~, filename.bak).If a file is not beneficial to someone using the IPOL software, it MUST NOT be included in the software.
An IPOL software MUST include all the material necessary to build one or more executable programs implementing the algorithm published in IPOL. This material MUST be provided in human-readable source code form. An IPOL software MUST NOT be distributed with binary pre-compiled files if they can be obtained from source code. If the authors want to distribute binary versions, this MUST be done out of the IPOL software archive.
The software SHOULD NOT be distributed with source code files not needed to build the implementation of the algorithm published in IPOL.
The source code of an IPOL software MUST be written in a compiled programming language and follow a published standard syntax; currently accepted standards are C89 (ANSI C), C99, and C++98 (ISO C++).
IPOL authors SHOULD test their software with the gcc compiler in strict compilation mode2 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 published standard, not on any vendor implementation.
The source code of an IPOL software MUST NOT require any extension of the language or its standard library, or any resource specific to a hardware environment or operating system. These extensions and resources MAY be used to achieve better performances if they are available but their availability MUST be detected by the software and an alternative portable implementation MUST be provided for alternative environments. This includes (but is not limited to)
drand48());__builtin_ia32_mulps());GetSystemTime(), POSIX gettimeofday());C:\Documents and Settings, /tmp);A special attention will be given to the Linux 64-bit environment, because it is currently the primary environment for IPOL demonstrations. But the software MUST also be usable in other environments and this portability MUST NOT be limited to the Win32/POSIX alternative.
An IPOL software MUST not use external software components except for the libraries and APIs listed hereafter:
libtiff version 3.x, libpng version 1.4.x to read and write image files;fftw version 3.x 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 software MUST use an automated build tool for the compilation. Either make or cmake can be used. 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 only use standard compiler options 3: -c, -D, -E, -g, -I, -L, -l, -O, -o, -s and -U.
An IPOL software 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.
It MUST read and write data files in standard and documented formats, such as (but not limited to) PNG or TIFF image files, EPS or SVG vector files, PLY or VRML meshes. For images, the main IPOL data type, an IPOL software MAY only read one image file format.
Annex B. provides some information for IPOL authors to help them use external libraries to read and write images and perform various frequent coding tasks.
In the shared IPOL demo environment, an IPOL program SHOULD NOT use more than 1 GiB of memory, and 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 software.
In an IPOL software, 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 correctness, clarity and reusability of their software.
The source code of an IPOL software MUST be written in English; all the variables, functions and comments MUST be written in English. It MUST be consistently indented and spaced. Lines SHOULD be limited to 79 characters and there MUST NOT be any whitespace at the end of the lines. The DOS CR+LF line terminator MUST NOT be used. Files SHOULD NOT have more than 1000 lines, they MUST end with a correcly terminated line and there SHOULD NOT be empty lines at the end of a file.
Functions SHOULD be grouped in different source code files by abstraction level: the main() function, command-line options and input/output processing in a file, and all the algorithm implementation in one or more other files.
Authors MUST avoid unnecessary programming tricks that shorten the code but make in fact its comprehension difficult to nonprofessional programmers.
Detailed coding guidelines will be released later with recommendations for IPOL software. Comments and documentation requirements are detailed in the Source Code Documentation section of this document.
Every source code file in a software submitted to IPOL MUST mention its author or 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, in case of a file based on a previous work, 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 or web site.
An simple example for a single author can be:
Copyright (c) 2011, Jane Doe <jane.doe@example.org>
All rights reserved.
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.fr>
All rights reserved.
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. It MUST be a free software license of the GPL or BSD type. The license MUST be mentioned after the copyright attribution line (and patent warning for algorithms potentially linked to a patent). 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>.
The exact terms can differ, for example when a different GPL license version is chosen. The full text of the license MUST be included in a separate file with the source code, for every license used.
IPOL authors SHOULD verify that the usage of these licenses for their software publications complies with their employer policy and local situation and jurisdiction.
When a file can be linked to a patented algorithm, GPL licenses MUST NOT be used because they might conflict with patents or are somehow unclear. BSD licenses can be used but some of their terms may be restricted by patent jurisdictions.
As a special exception to the IPOL policy, the authors of a source code file MAY decide that this file is provided “for scientific and educational purposes only”. This exception can help avoiding problems when the authors are the patent owners: distributing the source code with a free software license could conflict with their patent rights. This exception is not necessary for other patents because the patent warning states that the license only applies if it doesn’t conflict with the patent rights. This wording is RECOMMENDED:
This program is provided for scientific and educational 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.
Every IPOL software MUST include a basic information file named README.txt in the base folder and written in plain text format, in English, in ANSI or UTF8 encoding. This README.txt MUST include the following information, in any order:
This README.txt file MAY be completed by another documentation, possibly with more details, in text, PDF, HTML or any other file format.
For simple code, the license information can be
This software is written by Jane Doe <jane.doe@example.org> and
distributed under the terms of the GPLv3 license.
A complex case (multiple authors and licenses, patents) can be:
This software 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 header 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.
The source code of an IPOL Software MUST be very readable, commented precisely and exhaustively. Comments MUST be abundant and SHOULD attain the 1/8 comment/instruction ratio but the quality of these comments is more important than the quality.
Each part of the implementation MUST be linked to the respective part of the mathematical description of the algorithm. Every choice in the implementation MUST be explained.
Every function MUST be documented with at least a line explaining what the function is doing, and the meaning of every parameter and return value.
The Doxygen source code documentation format is RECOMMENDED for every IPOL Software.
The annexes are not part of the policy. They are provided to help authors and editors follow the policy. If the information provided in the annex conflicts with the policy, the policy stands and the annex is considered wrong.
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”), gzip and zip (usually “Info-Zip zip”) programs;tar (usually “BSD tar”) and gzip programs and the “Create Archive” feature of the graphical interface;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 collection 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.
This short list is a summary of the guidelines, to quickly check an IPOL software:
name_version.{zip,tar.gz,tgz}name_version foldergcc -std=xx -Wall -Wextra -Werrorlibtiff, libpng, fftw, cblas and clapack external librariesmake or cmake$(CC) or $(CXX) with only standard optionsmain() and algorithmic code in different filesREADME.txt documentation summaryA tool to check an IPOL software against the guidelines is available at http://tools.ipol.im/xxx. It detects the major violations of these guidelines and can be used to quickly test a software before submission. The absence of error reported by this tool doesn’t imply that all the guidelines are correctly followed.
These file formats are defined by the PKZIP APPNOTE specification, version 6.3.2, for the .ZIP compressed archive format, the IETF RFC1952 for the GZIP compressed format, and the POSIX.1 ustar definition for the tar archive format. ↩
C89, C99 and C++98 code can be tested with gcc -std=c89, gcc -std=c99 and gcc -std=c++98 and the -Wall -Wextra -Werror options. ↩
standard options are defined by the POSIX c99 specification. ↩