#

# CDDL HEADER START

#

# The contents of this file are subject to the terms of the

# Common Development and Distribution License, Version 1.0 only

# (the "License"). You may not use this file except in compliance

# with the License.

#

# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

# or http://www.opensolaris.org/os/licensing.

# See the License for the specific language governing permissions

# and limitations under the License.

#

# When distributing Covered Code, include this CDDL HEADER in each

# file and include the License file at usr/src/OPENSOLARIS.LICENSE.

# If applicable, add the following below this CDDL HEADER, with the

# fields enclosed by brackets "[]" replaced with your own identifying

# information: Portions Copyright [yyyy] [name of copyright owner]

#

# CDDL HEADER END

#

Writing PKCS11 Library Makefiles

================================

Copyright 2004 Sun Microsystems, Inc. All rights reserved.

Use is subject to license terms.

ident "%Z%%M% %I% %E% SMI"

Introduction

------------

This document assumes that you are already familiar with writing

library Makefiles. See usr/src/lib/README.Makefiles.

The guidelines for pkcs11_softtoken libraries are more specific than

those for library makefiles, in general. But they are in addition

to, and consistent with the more general guidelines.

Just the rules

--------------

pkcs11_softtoken/<isa>/Makefile:

pkcs11_softtoken_extra/<isa>/Makefile:

These files contain only one statement, other than comments:

include ../../Makefile.softtoken.<isa>

Makefile.softtoken.<isa>:

These Makefiles define ONLY the ISA-specific definitions

and targets. For each encryption algorithm, <algo>,

(such as AES, DES, SHA1, etc.), the list of ISA-specific

object files is defined; the variable <algo>_PSR_OBJECTS

is set. To ensure that all relavent source files are

examined by lint, XXX_PSR_SRCS is set. ISA-specific additions

to CCPFLAGS, CFLAGS, etc. are set here.

In general, variables describing processor-specific files

have _PSR_ as part of the variable name.

After all ISA-specific definitions, Makefile.com is included.

The actual include statement is "include ../Makefile.com".

Remember that the path specified in all include statements

is from the point of view of the current working directory,

not the directory that contains the Makefile being read in

currently. So, in the case of nested includes, paths cannot

be expressed in terms relative to the including Makefile.

Even though Makefile.softtoken.<isa> is including ../Makefile.com,

at this stage, it is including a file that is below it in

the directory tree. The Makefile.com file is common to all

ISAs, but specific to either softtoken or softtoken_extra.

pkcs11_softtoken/Makefile.com:

Just defines LIBRARY and VERS; then includes Makefile.softtoken.com

pkcs11_sottoken_extra adds the C preprocessor symbol, CRYPTO_UNLIMITED.

This is the only thing that distinguishes pkcs11_softtoken_extra

behavior from just plain pkcs11_softtoken. All targets and

definitions are otherwise the same for "plain" and "extra".

Makefile.softtoken.com:

contains all definitions and targets common to pkcs11_softtoken

and pkcs11_softtoken_extra, for all ISAs. It should not

contain any ISA-specific targets or definitions. The practice

of constructing "common" definitions by using nested macro

names is deprecated. So, for example, there should be no use

of variables such as $(XXX_$(TRANSMACH)).

Rationale

---------

ISA-specific targets and definitions are deferred, in keeping with

the general guidelines for library makefiles.

Poor-man's OO programming

If we used a system for building complex software systems that was

target-driven, as make(1) is, and also had language support for

object-oriented programming, then we would define generic classes

and templates for things like libraries and commands, and each

library or command would deal with the specifics in a subclass.

This is the build system of the future, and it always will be.

Make has no OO language support. Make has been around for a long

time, and will likely be around for a long time to come.

So, we get along with poor-man's OO programming by source code

inclusion, rather than importing packages/modules/classes.

This is the oldest and most primitive form of code reuse, but

it is better than nothing, and it works. But, there are dangers.

There are definite rules for when macro definitions and other non-target

statements are evaluated, and when command lines withing targets

are evaluated. But, it can be confusing, sometimes. In general, it

is not a good idea to include a super-class Makefile more than once.

Not all make statements are idempotent. All this makes this system of

makefiles tricky to maintain. It is not easy to just parachute in, and

see how one's innocent local change might affect other things, due to

"action at a distance".

What makes pkcs11 special?

There are many other commands and libraries that get by without

their own README.Makefiles. Why does pkcs11 need one?

1. pkcs11_softtoken Makefiles incorporate code that is common

to userland libraries and kernel modules. So, not everything

is in local directories, and not everything can be handled by

simple suffix rules. Some code is local and some comes from

usr/src/common.

2. The pkcs11_softtoken library comes in two "flavors", pkcs11_softtoken

and pkcs11_softtoken_extra. Simple repetition of logic in the

ISA-specific subdirectories would lead to unnecessary maintenance

work and increase the chances of unintended code divergence.

3. Many ISA-specific object files have ISA-specific names, rather

than having a common name for the .c and .o files for different

implementations.

4. Some implementations have multiple ISA-specific object files.

So, the list of object files changes, not just the choice of

contents of each object file.

Why deprecate $(XXX_$(TRANSMACH)) and friends?

If we adhere to the discipline of strictly ISA-specific targets

and definitions in the ISA-specific makefiles, and doing that

first, before including super-class makefiles, then we avoid

many of the problems associated with doing it the other way

around. Macro defintions that rely on $(TRANSMACH), for example,

depend on the super-class makefile having been included, first,

just in order to "inherit" the definition of TRANSMACH. But,

other contents of some super-class makefiles make sense only

after ISA-specific things have been defined. So, directly

or indirectly, some super-class makefiles get included twice.

Some super-class makefiles consist entirely of statements that

are safe for multiple inclusion. Others do not.