[Proftpd-docs] CVS: www.proftpd.org/docs/howto DSO.html,1.2,1.3

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/pdd/www.proftpd.org/docs/howto
In directory sfp-cvsdas-2.v30.ch3.sourceforge.com:/tmp/cvs-serv30891

Modified Files:
	DSO.html 
Log Message:

Updating website copy of DSO howto.

Index: DSO.html
===================================================================
RCS file: /cvsroot/pdd/www.proftpd.org/docs/howto/DSO.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -r1.2 -r1.3
*** DSO.html	15 Oct 2007 16:25:04 -0000	1.2
--- DSO.html	5 Jan 2010 17:01:24 -0000	1.3
***************
*** 170,176 ****

    INSTALL=/usr/bin/install -c
!   INSTALL_USER=user
!   INSTALL_GROUP=user
!   INSTALL_BIN=$(INSTALL) -s -o $(INSTALL_USER) -g $(INSTALL_GROUP) -m 0755

    LIBTOOL=$(SHELL) /usr/bin/libtool
--- 170,174 ----

    INSTALL=/usr/bin/install -c
!   INSTALL_BIN=$(INSTALL) -s -m 0755

    LIBTOOL=$(SHELL) /usr/bin/libtool
***************
*** 188,197 ****

    install: $(MODULE_NAME).la
!           $(LIBTOOL) --mode=install $(INSTALL_BIN) $(MODULE_NAME).la $(DESTDIR)$(LIBEXEC_DIR)

    clean:
!           $(LIBTOOL) --mode=clean $(RM) $(MODULE_NAME).la
!           $(LIBTOOL) --mode=clean $(RM) $(MODULE_NAME).lo
!           $(RM) config.*

    distclean:
--- 186,195 ----

    install: $(MODULE_NAME).la
!           if [ -f $(MODULE_NAME).la ] ; then \
!                   $(LIBTOOL) --mode=install $(INSTALL_BIN) $(MODULE_NAME).la $(DESTDIR)$(LIBEXEC_DIR) ; \
!           fi

    clean:
!           $(LIBTOOL) --mode=clean $(RM) $(MODULE_NAME).la $(MODULE_NAME).lo config.*

    distclean:
***************
*** 220,227 ****
  </pre>
  The <code>make install</code> step will install the DSO module into the
! <code>libexec/</code> directory of your ProFTPD install location.  Note that
! you may need to tweak the <code>INSTALL_USER</code> and
! <code>INSTALL_GROUP</code> variables with the necessary user/group names for
! installing the DSO module.

  <p>
--- 218,222 ----
  </pre>
  The <code>make install</code> step will install the DSO module into the
! <code>libexec/</code> directory of your ProFTPD install location.

  <p>
***************
*** 233,236 ****
--- 228,323 ----
  Then restart <code>proftpd</code>, and your custom module will be in use.

+ <p><a name="prxs"></a>
+ <b>Using <code>prxs</code></b><br>
+ You may find yourself wanting to compile some third-party module, for which
+ you have the source code, as a DSO module for proftpd.  But you may not have
+ the source code for proftpd, <i>e.g.</i> you might have installed proftpd
+ as a binary package.  The build system for proftpd would let you compile
+ your third-party module as a DSO module, but what do you do if you don't have
+ access to the proftpd build system?
+ 
+ <p>
+ The answer is to use the <code>prxs</code> script, which comes with proftpd.
+ The <code>prxs</code> (<b>PR</b>oFTPD E<b>X</b>tension<b>S</b>) tool will
+ compile and install third-party modules, from source code, as DSO modules
+ for your installed proftpd.
+ 
+ <p>
+ The <code>prxs</code> tool supports the following actions:
+ <pre>
+  -c, --compile          Compiles the listed <code>.c</code> source files
+                         into a proftpd DSO module.
+ 
+  -i, --install          Installs a compiled proftpd DSO module into the
+                         directory where proftpd expects to find loadable
+                         DSO modules.
+ 
+  -d, --clean            Removes any generated files, returning the build
+                         directory to a clean state.
+ </pre>
+ At least one of the above actions must be specified when using
+ <code>prxs</code>.  More than one action can be specified at the same time.
+ 
+ <p>
+ To use <code>prxs</code> all in one step, you could do:
+ <pre>
+   # prxs -c -i -d mod_custom.c
+ </pre>
+ which will do the compile, install, and clean actions in order.  Once
+ installed, update your <code>proftpd.conf</code> to make sure your module is
+ loaded:
+ <pre>
+   LoadModule mod_custom.c
+ </pre>
+ Then restart <code>proftpd</code>, and your custom module will be in use.
+ 
+ <p>
+ The following options are also supported:
+ <pre>
+  -n, --name             Tells prxs the name of the module being compiled.
+                         By default, prxs determines the module name from
+                         the list of .c files listed, expecting to see a
+                         "mod_<i>name</i>.c" file.
+ 
+  -D key                 Passes these macros through to the compilation step.
+  -D key=value           Note that the space before the key is important.
+ 
+  -I <em>includedir</em> Specify additional include file search directories.
+                         Note that the space before the directory is important.
+ 
+  -L <em>libdir</em>     Specify additional library file search directories.
+                         Note that the space before the directory is important.
+ 
+  -l <em>library</em>    Specify additional libraries for linking.
+                         Note that the space before the library name is important.
+ </pre>
+ 
+ <p>
+ Using <code>prxs</code>, the above <code>mod_custom</code> example would
+ become:
+ <pre>
+   # cd /path/to/mod_custom/dir
+   # prxs -c -i -D USE_CUSTOM -I /path/to/custom/include -L /path/to/custom/lib -l custom mod_custom.c
+ </pre>
+ That's it!  No need for a special Makefile, and no need to edit/replace any
+ variables.
+ 
+ <p>
+ The <code>prxs</code> tool uses the <code>libtool</code> command that your
+ system should support.  If you need to tell <code>prxs</code> to use a
+ different <code>libtool</code> for any reason (such as using a specially
+ installed <code>libtool</code>), you can use the <code>LIBTOOL</code>
+ environment variable to point <code>prxs</code> to the <code>libtool</code>
+ to use.  For example:
+ <pre>
+   # LIBTOOL=/path/to/custom/libtool prxs -c -i -d mod_custom.c
+ </pre>
+ 
+ <p>
+ When should you use <code>prxs</code> for compiling DSO modules, and when
+ should you use a Makefile?  In general, if the third-party module comes with
+ its own <code>configure</code> script and <code>Makefile</code>, then you
+ should use those.  Otherwise, <code>prxs</code> should suffice.
+ 
  <p>
  <hr>