|
|
@@ -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
|
Jonathan Pryor