added a document on how to port smbwrapper to a new system

(This used to be commit bf1e257afb51f93e707bd7c1f75c8a2b35e69bed)

source3/smbwrapper/PORTING

@@ -0,0 +1,77 @@
+This describes how to port the smbwrapper portion of Samba to a new
+unix-like platform. Note that porting smbwrapper is considerably
+harder than porting Samba, for Samba you generally just need to run
+configure and recompile whereas for smbwrapper some extra effort is
+generally required.
+
+
+STEP 1
+------
+
+The first step is to work out how to create a shared library on your
+OS and how to compile C code to produce position independent object
+files (PIC files). You shoud be able to find this information in the
+man pages for your compiler and loader (ld). Then modify configure.in
+to give that information to Samba.
+
+
+STEP 2
+------
+
+The next step is to work out how to preload shared objects. On many
+systems this is done using a LD_PRELOAD environment variable. On
+others (shc as IRIX) it may use a _RTL_LIST variable.
+
+To make sure it works I suggest you create two C files like this:
+
+/* first C file */
+main()
+{
+ unlink("foo.txt");
+}
+
+/* second C file */
+#include <stdio.h>
+
+int unlink(char *fname)
+{
+	fprintf(stderr,"unlink(%s) called\n",fname);
+}
+
+
+then compile the first as an ordinary C program and the second as a
+shared library. Then use LD_PRELOAD to preload the resulting shared
+library. Then run the first program. It should print "unlink(foo.txt)
+called". If it doesn't then consult your man pages till you get it
+right.
+
+Once you work this out then edit smbwrapper/smbsh.in and add a section
+if necessary to correctly set the necessary preload options for your
+OS. 
+
+
+STEP 3
+------
+
+The next step is to work out how to make direct system calls. On most
+machines this will work without any source code changes to
+smbwrapper. To test that it does work create the following C program:
+
+#include <sys/syscall.h>
+main()
+{
+ syscall(SYS_write, 1, "hello world\n", 12);
+}
+
+and try to compile/run it. If it produces "hello world" then syscall()
+works as expected. If not then work out what needs to be changed and
+then make that change in realcalls.h. For example, on IRIX 6.4 the
+system call numbers are wrong and need to be fixed up by getting an
+offset right.
+
+
+STEP 4
+------
+
+Try compiling smbwrapper! Then test it. Then debug it. Simple really :)
+