* man/mono-shlib-cop.1: Add man page for mono-shlib-cop program.

svn path=/trunk/mono/; revision=45879

diff --git a/ChangeLog b/ChangeLog
index 51c1850de4fff58137f587c610581e8b920640c9..f7caeed80be51e46cec58cd7046cc097f25397c5 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2005-06-13  Jonathan Pryor <jonpryor@vt.edu>
+
+       * man/mono-shlib-cop.1: Add man page for mono-shlib-cop program.
+
 2005-06-13  Jonathan Pryor <jonpryor@vt.edu>
 
        * data/config.in: Fix generated XML.

diff --git a/man/mono-shlib-cop.1 b/man/mono-shlib-cop.1
new file mode 100644 (file)
index 0000000..4a9bf51
--- /dev/null
+++ b/man/mono-shlib-cop.1
@@ -0,0 +1,151 @@
+.TH "mono-shlib-cop" 1
+.SH NAME
+mono-shlib-cop \- Shared Library Usage Checker
+.SH SYNOPSIS
+.B mono-shlib-cop
+[OPTIONS]* [ASSEMBLY-FILE-NAME]*
+.SH OPTIONS
+.TP
+.I \-p, --prefixes=PREFIX
+Mono installation prefixes.  This is to find $prefix/etc/mono/config.
+The default is based upon the location of mscorlib.dll, and is normally
+correct.
+.PP
+.SH DESCRIPTION
+.I mono-shlib-cop 
+is a tool that inspects a managed assembly looking for
+erroneous or suspecious behavior of shared libraries.
+.PP
+The tool takes one or more assembly filenames, and inspects each assembly
+specified.
+.PP
+The errors checked for include:
+.TP 
+*
+Does the shared library exist?
+.TP
+*
+Does the requested symbol exist within the shared library?
+.PP
+The warnings checked for include:
+.TP
+*
+Is the target shared library a versioned library?  (Relevant only on Unix
+systems, not Mac OS X or Windows.)
+.PP
+In general, only versioned libraries such as libc.so.6 are present on the 
+user's machine, and efforts to load libc.so will result in a 
+System.DllNotFoundException.  There are three solutions to this:
+.TP 
+1.
+Require that the user install any -devel packages which provide the 
+unversioned library.  This usually requires that the user install a large
+number of additional packages, complicating the installation process.
+.TP
+2.
+Use a fully versioned name in your DllImport statements.  This requires
+editing your source code and recompiling whenever you need to target a
+different version of the shared library.
+.TP
+3.
+Provide an assembly.config file which contains <dllmap/> elements to remap
+the shared library name used by your assembly to the actual versioned shared
+library present on the users system.  Mono provides a number of pre-existing
+<dllmap/> entries, including libc.so and libX11.so.
+.SH EXAMPLE
+The following code contains examples of the above errors and warnings:
+.nf
+       using System.Runtime.InteropServices; // for DllImport
+       class Demo {
+               [DllImport ("bad-library-name")]
+               private static extern void BadLibraryName ();
+
+               [DllImport ("libc.so")]
+               private static extern void BadSymbolName ();
+
+               [DllImport ("libcap.so")]
+               private static extern int cap_clear (IntPtr cap_p);
+       }
+.fi
+.TP
+Bad library name
+Assuming that the library 
+.B bad-library-name
+doesn't exist on your machine, Demo.BadLibraryName will generate an error, as
+it requires a shared library which doesn't exist.
+.TP
+Bad symbol name
+Demo.BadSymbolName will generate an error, as libc.so (remapped to libc.so.6
+by mono's $prefix/etc/mono/config file) doesn't contain the function
+BadSymbolName.
+.TP
+Unversioned library dependency
+Assuming you have the file libcap.so, Demo.cap_clear will generate a
+warning because, while libcap.so could be loaded, libcap.so might not exist on
+the users machine (on FC2, /lib/libcap.so is provided by 
+.I libcap-devel
+, and you can't assume that end users will have any -devel packages installed).
+.SH FIXING CODE
+The fix depends on the warning or error:
+.TP
+Bad library names
+Use a valid library name in the DllImport attribute, or provide a <dllmap/>
+entry to map your existing library name to a valid library name.
+.TP
+Bad symbol names
+Reference a symbol that actually exists in the target library.
+.TP
+Unversioned library dependency
+Provide a <dllmap/> entry to reference a properly versioned library, or ignore
+the warning (see 
+.B BUGS
+).
+.SH DLLMAP ENTRIES
+Mono looks for an
+.I ASSEMBLY-NAME
+\.config file for each assembly loaded, and reads this file to find Dll
+mapping information.  For example, with
+.I mcs.exe
+, Mono would read 
+.I mcs.exe.config
+, and for 
+.I Mono.Posix.dll
+, Mono would read 
+.I Mono.Posix.dll.config
+\.
+.PP
+The .config file is an XML document containing a top-level <configuration/>
+section with nested <dllmap/> entries, which contains 
+.B dll
+and
+.B target
+attributes.  The dll attribute should contain the same string used in your
+DllImport attribute value, and the target attribute specifies which shared
+library mono should 
+.I actually
+load at runtime.
+.PP
+A sample .config file is:
+.nf
+       <configuration>
+               <dllmap dll="gtkembedmoz" target="libgtkembedmoz.so" />
+       </configuration>
+.fi
+.SH BUGS
+.I mono-shlib-cop
+currently only examines the shared library file extension to determine if a
+warning should be generated.  A
+.I .so
+extension will always generate a warning, even if the .so is not a symlink,
+isn't provided in a -devel package, and there is no versioned shared library 
+(possible examples including /usr/lib/libtcl8.4.so, /usr/lib/libubsec.so,
+etc.).
+.PP
+Consequently, warnings for any such libraries are useless, and incorrect.
+.PP
+Windows and Mac OS X will never generate warnings, as these
+platforms use different shared library extensions.
+.SH MAILING LISTS
+Visit http://lists.ximian.com/mailman/listinfo/mono-devel-list for details.
+.SH WEB SITE
+Visit http://www.mono-project.com for details