Here is a quickie guide to get you started in IPA development.

Dependencies
------------

The quickest way to get the dependencies needed for building is:

# yum install rpm-build `grep "^BuildRequires" freeipa.spec.in | awk '{ print $2 }' | grep -v "^/"`

This is currently (2014-02-11):

yum install rpm-build 389-ds-base-devel svrcore-devel policycoreutils \
systemd-units samba-devel samba-python libwbclient-devel samba4-devel \
samba4-python libtalloc-devel libtevent-devel nspr-devel nss-devel \
openssl-devel openldap-devel krb5-devel krb5-workstation libuuid-devel \
libcurl-devel xmlrpc-c-devel popt-devel autoconf automake m4 libtool gettext \
python-devel python-ldap python-setuptools python-krbV python-nss \
python-netaddr python-kerberos python-rhsm pyOpenSSL pylint python-polib \
libipa_hbac-python python-memcached sssd python-lxml python-pyasn1 \
python-qrcode python-dns m2crypto check libsss_idmap-devel \
libsss_nss_idmap-devel java-1.7.0-openjdk libverto-devel systemd \
libunistring-devel python-lesscpy

Building
--------

From the root of the source tree run:
$ make rpms

The resulting rpm packages are in dist/rpms:

# yum --nogpgcheck localinstall dist/rpms/*
# ipa-server-install

It may be possible to do a simple make all install but this has not been
well-tested. Additional work is done in pre/post install scripts in the ipa
spec file.

Developing plugins
------------------

It is possible to do management plugin development within the source tree.

To start with, you need a full IPA install on the current system. Build and
install the rpms and then configure IPA using ipa-server-install.

Get a TGT for the admin user with: kinit admin

Next you'll need 2 sessions in the source tree. In the first session run
python lite-server.py. In the second session you can run the ./ipa
tool and it will make requests to the lite-server listening on 127.0.0.1:8080.

This makes developing plugins much faster and you can also make use of the
Python pdb debugger on the server side.

You'll find you may need to refresh the underlying build if schema or other
changes are required.

Testing
-------

For more information, see http://www.freeipa.org/page/Testing

We use python nosetests to test for regressions in the management framework
and plugins. All test dependencies are required by the freeipa-tests package.

To run all of the tests you will need 2 sessions, one to run the lite-server
and the other to execute the tests. You'll also need a TGT before starting
the lite-server:

% kinit admin
% make test

Some tests may be skipped. For example, all the XML-RPC tests will be skipped
if you haven't started the lite-server. The DNS tests will be skipped if
the underlying IPA installation doesn't configure DNS, etc.

API.txt
-------
The purpose of the file API.txt is to prevent accidental API changes. The
program ./makeapi creates file and also validates it (with the --validate
option). This validation is part of the build process.

There are three solutions to changes to the API:

1. Changes to existing API require a change to the MAJOR version.
2. Addition of new API requires a change to the MINOR version.
3. Or just back out your changes and don't make an API change.

If the API changes you'll need to run ./makeapi to update API.txt and
commit it along with VERSION with your API change.

If a module is optionally loaded then you will need to be able to
conditionally load it for API validation. The environment variable
api.env.validate_api is True during validation.

General Notes
-------------
IPA is not relocatable.

When building rpms the version contains the GIT id in the version. To prevent
this pass the argument IPA_VERSION_IS_GIT_SNAPSHOT=yes to make.