README.md

The Chemistry Development Kit (CDK)

Copyright 1997-2016 The CDK Development Team

License: LGPL v2, see doc/lgpl.license

Introduction

You are currently reading the README file for the Chemistry Development Project (CDK).
This project is hosted under http://cdk.sourceforge.net/
Please refer to these pages for updated information and the latest version of the CDK. CDK's API documentation is available though our Github site.

The CDK is an open-source library of algorithms for structural chemo- and bioinformatics, implemented in
the programming language Java(tm). The library is published under terms of the the
GNU Lesser General Public License v2. This has implications on what you can do with sources and
binaries of the CDK library. For details, please refer to the file LICENSE, which should have been
provided with this distribution.

PLEASE NOTE: This is a library of useful data structures and algorithms to manipulate them
from the area of structural chemo- and bioinformatics. As such, it is intended for the use by
programmers, who wish to save some effort by reusing code. It is not intended for the enduser.
If you consider yourself to be more like user, you might not find what you wanted.
Please refer to other projects like the JChemPaint project (http://jchempaint.github.com/)
or the Jmol project (http://www.jmol.org/) for programs that actually take advantage of the
CDK library.

Compiling

Compiling the library is performed with Apache Maven and requires Java 1.7 or later:

cdk/$ ls pom.xml
pom.xml
cdk/$ mvn compile

This will produce a 'jar' file for each module located in each modules 'target/' directory.

Creating the JavaDoc

The JavaDoc documentation for the API describes all of the CDK classes in detail. It functions as
the user manual for the CDK, although you should also look at the list of examples and tutorials
below.

Before creating the JavaDoc you will need to install the CDK build util project in your local maven repo.

Using CDK

CDK is a class library intended to be used by other programs. It will not run
as a stand-alone program, although it contains some GUI- and command
line applications. If your project is also using maven you can install the
library in your local repository (~/.m2/repository) as follows:

cdk/$ mvn install -Dmaven.test.failure.ignore=true

A large bundled jar with all dependencies can also be built. If you have locally
made modifications to the source code you will need to install these to your
local repository. The jar will in the target directory of the 'bundle' module.

If you have not made any changes you need only package the bundle module. The other
modules will be automatically downloaded.

cdk/$ cd bundle
cdk/$ mvn package
cdk/$ ls target/cdk-{version}.jar

Maven Artefacts

Maven artefacts of each module are deployed to the Maven Central Repository. To use a CDK module
just specify the dependency in your pom.xml. Any additional requirements of the module will
also be downloaded and included.

Maven reporting plugins

This section details how to run the plugins and access the reports.

PMD

PMD analyses code style (e.g. variable naming, complexity) and reports potential bugs. Currently only production (non-test) code is inspected. The following snippet shows how to run PMD on the 'cdk-silent' module.

java-formatter

As a relatively mature project with many different developers there are many different formatting styles used in the CDK source code. Following patches from different IDEs with different settings some files have gotten pretty messy. The java-formatter tidies up the code using consistent settings.

JaCoCo

JaCoCo is a tool for analysing test coverage. JaCoCo can install agent instrumentation and check exactly which lines are called and missed by tests. This not only serves as a quality measure but also can guide optimisation, "why isn't that conditional ever hit by my tests, is it even possible?".

The contribute method determines the number of pi electrons for an element with specified valence (v) and connectivity (x). We can see that two lines are flagged as yellow. On inspection we can see that 1 of 4 branches was missed. There are four branches because of two conditionals (2^2=4) and one of them is missed.

IDEs and CI servers (Jenkins) can also integrate the reports directly.

Reporting coverage when the tests are separate to the production code is a little more tricky but possible. Here is an example for the 'cdk-standard' module.