" CDDL HEADER START
"
" The contents of this file are subject to the terms of the
" Common Development and Distribution License (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
"
"Copyright 2009 Sun Microsystems, Inc. All rights reserved.
"Use is subject to license terms.
findunref - find unused files in a source tree findunref [-s subtree] [-t tstampfile] [-S hg|tw] srcroot exceptfile

"OS-Net build tools" "findunref" "" "findunref"

The findunref utility lists the files in a source tree which have not been accessed more recently than a particular timestamp file. Although findunref may be used on its own, it is usually invoked by nightly(1) to find files that are never referenced during a given build (see -f in nightly(1)).

The root of the source tree to examine is specified by srcroot. To simplify comparing findunref output from different source trees, findunref outputs all filenames relative to srcroot.

Some files in a source tree may be intentionally unreferenced (e.g., documentation) or only referenced during specialized types of builds. Accordingly, exceptfile names a file containing a list of pathname globs that will be ignored by findunref. Within exceptfile, any lines consisting solely of whitespace or starting with # will be ignored. Directory globs may also be specified, which will cause any matching directories to be skipped entirely. If no exceptions are desired, exceptfile can be /dev/null.

Depending on how findunref is invoked, it can either check all files, or limit its checks to files under control of a specific source code management (SCM) system. To limit checks to files managed by Mercurial, the hg(1) utility must be present in /usr/bin and any relevant repositories must be located at or under srcroot. Nested Mercurial repositories are supported.

10 -s subtree Only look under subtree for unreferenced files. By default, all directories under srcroot are examined.

10 -t tstampfile Consider files older than tstampfile to be unreferenced. By default, srcroot/.build.tstamp is used.

10 -S hg|tw Only check files that are managed by the specified SCM. To simplify interaction with which_scm(1), the SCM names "mercurial" and "teamware" may also be specified. By default, all files are checked.

hg(1), nightly(1), which_scm(1)

Since many files are only used when building for a particular ISA (e.g., Makefiles that are specific to x86 or SPARC), builds must be done on all applicable ISAs and the results merged. For instance, if nightly builds (with -f) are done on both SPARC and x86, usr/src will be populated with a corresponding unref-isa.out file, which can be merged with comm(1):

comm -12 /path/to/unref-i386.out
 /path/to/unref-sparc.out > unref.out 

This merged file can then be compared against the gate's latest unreferenced file list (e.g. /ws/onnv-gate/usr/src/unrefmaster.out).

Different gates have different unreferenced file policies. Any changes to exceptfile that would define new unreferenced file policies for a given gate must be cleared with the appropriate gatekeepers.