Build(plasticfs)                                              Build(plasticfs)



NAME
        PlasticFS - The Plastic File System

SPACE REQUIREMENTS
        You will need about 3MB to unpack and build the PlasticFS package.
        Your milage may vary.

BEFORE YOU START
        There are a few pieces of software you may want to fetch and install
        before you proceed with your installation of PlasticFS.

        GNU Groff
                The documentation for the PlasticFS package was prepared using
                the GNU Groff package (version 1.14 or later).  This
                distribution includes full documentation, which may be
                processed into PostScript or DVI files at install time - if
                GNU Groff has been installed.

        GCC     You may also want to consider fetching and installing the GNU
                C Compiler if you have not done so already.  This is not
                essential.  PlasticFS was developed using the GNU C++
                compiler, and the GNU C++ libraries.
                Note: There appear to be problems with GCC 3.0 and later.  If
                you are expreiencing problems, try turning off all
                optimization.  If you have the option, use one of the older
                (2.96) versions.

        GNU Libtool
                The shared library is created using GNU Libtool.  It is
                assumed to be installed in the $PATH.

        The GNU FTP archives may be found at ftp.gnu.org, and are mirrored
        around the world.

SITE CONFIGURATION
        The PlasticFS package is configured using the configure program
        included in this distribution.

        The configure shell script attempts to guess correct values for
        various system-dependent variables used during compilation, and
        creates the Makefile and include/config.h files.  It also creates a
        shell script config.status that you can run in the future to recreate
        the current configuration.

        Normally, you just cd to the directory containing PlasticFS's source
        code and then type
                % ./configure
                ...lots of output...
                %
        If you're using csh on an old version of System V, you might need to
        type
                % sh configure
                ...lots of output...
                %
        instead to prevent csh from trying to execute configure itself.

        Running configure takes a minute or two.  While it is running, it
        prints some messages that tell what it is doing.  If you don't want to
        see the messages, run configure using the quiet option; for example,
                % ./configure --quiet
                %

        To compile the PlasticFS package in a different directory from the one
        containing the source code, you must use a version of make that
        supports the VPATH variable, such as GNU make.  cd to the directory
        where you want the object files and executables to go and run the
        configure script.  configure automatically checks for the source code
        in the directory that configure is in and in ..  (the parent
        directory).  If for some reason configure is not in the source code
        directory that you are configuring, then it will report that it can't
        find the source code.  In that case, run configure with the option
        --srcdir=DIR, where DIR is the directory that contains the source
        code.

        By default, configure will arrange for the make install command to
        install the PlasticFS package's files in /usr/local/bin, and
        /usr/local/man.  There are options which allow you to control the
        placement of these files.

        --prefix=PATH
                This specifies the path prefix to be used in the installation.
                Defaults to /usr/local unless otherwise specified.

        --exec-prefix=PATH
                You can specify separate installation prefixes for
                architecture-specific files files.  Defaults to ${prefix}
                unless otherwise specified.

        --bindir=PATH
                This directory contains executable programs.  On a network,
                this directory may be shared between machines with identical
                hardware and operating systems; it may be mounted read-only.
                Defaults to ${exec_prefix}/bin unless otherwise specified.

        --mandir=PATH
                This directory contains the on-line manual entries.  On a
                network, this directory may be shared between all machines; it
                may be mounted read-only.  Defaults to ${prefix}/man unless
                otherwise specified.

        configure ignores most other arguments that you give it; use the
        --help option for a complete list.

        On systems that require unusual options for compilation or linking
        that the PlasticFS package's configure script does not know about, you
        can give configure initial values for variables by setting them in the
        environment.  In Bourne-compatible shells, you can do that on the
        command line like this:
                $ CXX='g++ -traditional' LIBS=-lposix ./configure
                ...lots of output...
                $
        Here are the make variables that you might want to override with
        environment variables when running configure.

        Variable: CXX
                C++ compiler program.  The default is c++.

        Variable: CPPFLAGS
                Preprocessor flags, commonly defines and include search paths.
                Defaults to empty.  It is common to use
                CPPFLAGS=-I/usr/local/include to access other installed
                packages.

        Variable: INSTALL
                Program to use to install files.  The default is install if
                you have it, cp otherwise.

        Variable: LIBS
                Libraries to link with, in the form -lfoo -lbar.  The
                configure script will append to this, rather than replace it.
                It is common to use LIBS=-L/usr/local/lib to access other
                installed packages.

        If you need to do unusual things to compile the package, the author
        encourages you to figure out how configure could check whether to do
        them, and mail diffs or instructions to the author so that they can be
        included in the next release.

BUILDING PlasticFS
        All you should need to do is use the
                % make
                ...lots of output...
                %
        command and wait.

        If you have GNU Groff installed, the build will also create a
        etc/reference.ps file.  This contains the README file, this BUILDING
        file, and all of the man pages.

        You can remove the program binaries and object files from the source
        directory by using the
                % make clean
                ...lots of output...
                %
        command.  To remove all of the above files, and also remove the
        Makefile and include/config.h and config.status files, use the
                % make distclean
                ...lots of output...
                %
        command.

        The file etc/configure.in is used to create configure by a GNU program
        called autoconf.  You only need to know this if you want to regenerate
        configure using a newer version of autoconf.

TESTING PlasticFS
        The PlasticFS package comes with a test suite.

        The test will fail if you run them as root.  They are supposed to,
        because PlasticFS does nothing for root, it's a security thing (see
        plasticfs(3) for more information).  Run the tests as a normal user.

        To run the test suite, use the command
                % make sure
                ...lots of output...
                Passed All Tests
                %

        The tests take a few seconds each, with a few very fast, and a couple
        very slow, but it varies greatly depending on your CPU.

        If all went well, the message
                Passed All Tests
        should appear at the end of the make.

INSTALLING PlasticFS
        As explained in the SITE CONFIGURATION section, above, the PlasticFS
        package is installed under the /usr/local tree by default.  Use the
        --prefix=PATH option to configure if you want some other path.  More
        specific installation locations are assignable, use the --help option
        to configure for details.

        All that is required to install the PlasticFS package is to use the
                % make install
                ...lots of output...
                %
        command.  Control of the directories used may be found in the first
        few lines of the Makefile file and the other files written by the
        configure script; it is best to reconfigure using the configure
        script, rather than attempting to do this by hand.

GLIBC
        The GNU C Library, glibc, has some features in version 2.2 and later
        which make PlasticFS cease to work correctly.  These features ensure
        that the libc.so DSO loads as fast as possible, to the benefit of all
        applications.  This is accomplished by using a hidden PLT.  This is
        the default configuration of the GNU C Library.  For PlasticFS to work
        correctly, you need a version of libc.so without the hidden PLT.

        To build a version of libc.so without the hidden PLT, you need to have
        the sources for the exact version of the GNU C Library on your system.

        Most people use one of the Linux distributions, such a RedHat Linux.
        (If you built your own Linux, you probably stopped reading already.)
        Get your install disks and install the sources for the glibc package,
        the one with exactly the same version as is currently installed on
        your system.

   2.3 Series
        There is an undocumented glibc ./configure --disable-hidden-plt option
        which causes glibc not to use a hidden PLT.

        It is necessary to rebuild glibc using exactly the options used by the
        distribution maker.  In the case of options used by RPM, and all the
        distributions which use it, it is only necessary to read the spec
        file.  The only change is to add the ./configure --disable-hidden-plt
        option.

        At the end of the build there is a file called libc.so in the top-
        level of the build directory.  Install this next to the real libc.so
        as libc.nohidden.so to be used at the end of all LD_PRELOAD settings.
        Make sure it has the same owners and modes as the real libc.so file.

        When you upgrade you system, you will have to remember do do this all
        over again.

   2.2 Series
        This is the same as the 2.3 case, except that there is no convenient
        glibc ./configure --disable-hidden-plt option.

        It is necessary to patch include/libc-symbols.h as follows
                --- libc-symbols.h.orig 2003-07-07 21:31:22.000000000 +1000
                +++ libc-symbols.h      2003-07-07 21:31:43.000000000 +1000
                @@ -470,8 +470,7 @@
                    versioned_symbol (libc, __real_foo, foo, GLIBC_2_1);
                    libc_hidden_ver (__real_foo, foo)  */

                -#if defined SHARED && defined DO_VERSIONING \
                -    && !defined HAVE_BROKEN_ALIAS_ATTRIBUTE
                +#if 0
                 # ifndef __ASSEMBLER__
                 #  ifdef HAVE_BROKEN_VISIBILITY_ATTRIBUTE
                 #   define __hidden_proto_hiddenattr
        This is the net result of the NO_HIDDEN define present in glibc 2.3,
        and activated by the ./configure --disable-hidden-plt option.  It
        isn't available in 2.2, so we have to fake it.

        It is then necessary to rebuild glibc using exactly the options used
        by the distribution maker.  In the case of options used by RPM, and
        all the distributions which use it, it is only necessary to read the
        glibc spec file.

        At the end of the build there is a file called libc.so in the top-
        level of the build directory.  Install this next to the real libc.so
        as libc.nohidden.so to be used at the end of all LD_PRELOAD settings.

   Using libc.nohidden.so
        The LD_PRELOAD environment variable is actually a space-separated list
        of file names (see ld.so(8) for more information), searched in the
        order given.  To use PlasticFS you need to see the LD_PRELOAD
        environment variable as follows:
                LD_PRELOAD="libplasticfs.so libc.nohidden.so"
        Note that of you are going to preserve any existing preloaded modules,
        you need to ensure that libc.nohidden.so remains at the end, and you
        new module is at the beginning, something like
                LD_PRELOAD="libplasticfs.so $LD_PRELOAD libc.nohidden.so"
        should do what you need.

   Debian
        To rebuild glibc for a Debian based system, follow the usual
        instructions about building packages.
                apt-get install fakeroot dpkg-dev
                apt-get build-deps glibc
                apt-get source glibc
                cd glibc-2.3.6
        At this point you should see a glibc-2.3.6 directory (or whatever the
        appropriate version number is).  You need to edit the
        debin/rules.d/build.mk file
                --- rules.d/build.mk    2006-07-22 11:42:22.000000000 +1000
                +++ rules.d/build.mk    2006-07-22 11:07:49.000000000 +1000
                @@ -62,6 +62,7 @@
                                --build=$$configure_build --prefix=/usr --without-cvs                 --enable-add-ons=$(standard-add-ons)"$(call xx,add-ons)"                 --without-selinux +               --disable-hidden-plt                 $(call xx,with_headers) $(call xx,extra_config_options))

                        touch $@
        and then build as normal...
                dpkg-buildpackage -rfakeroot -b
        Once it is built, extract the libc.so file, and install it as
        libc.nohidden.so
                cp build-tree/i386-i686/libc.so /lib/libc.nohidden.so
        you should be all set.

   Replacing libc.so
        This is dangerous.  This will make your system slower.  Still want to?
        Make sure you have a rescue disk handly in case your system no longer
        works after the reboot and you have to put the original libc.so back.
        You did keep a copy, didn't you?

GETTING HELP
        If you need assistance with the PlasticFS package, please do not
        hesitate to contact the author at
                Peter Miller <millerp@canb.auug.org.au>
        Any and all feedback is welcome.

        When reporting problems, please include the version number given by
        the
                % PlasticFS -version
                PlasticFS version 1.11.D002
                ...warranty disclaimer...
                %
        command.  Please do not send this example; run the program for the
        exact version number.

COPYRIGHT
        PlasticFS version 1.11
        Copyright (C) 2002, 2003, 2004, 2006, 2007 Peter Miller; All rights
        reserved.

        The PlasticFS package is distributed in the hope that it will be
        useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
        General Public License for more details.

        It should be in the LICENSE file included with this distribution.

AUTHOR
        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/



Reference Manual                   plasticfs                  Build(plasticfs)
