# # 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//Makefile: pkcs11_softtoken_extra//Makefile: These files contain only one statement, other than comments: include ../../Makefile.softtoken. Makefile.softtoken.: These Makefiles define ONLY the ISA-specific definitions and targets. For each encryption algorithm, , (such as AES, DES, SHA1, etc.), the list of ISA-specific object files is defined; the variable _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. 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: pkcs11_softtoken_extra/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.