DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (be6b3af32106)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217
============================================
||  Upstream JSS Build/Test Instructions  ||
============================================

(1) Prepare a work area

    (a) For upstream builds which checkout and utilize
        the current NSPR and NSS source repositories:

        # mkdir sandbox
        # cd sandbox
        # hg clone https://hg.mozilla.org/projects/nspr
        # hg clone https://hg.mozilla.org/projects/nss
        # hg clone https://hg.mozilla.org/projects/jss
        # cd ..

        (There is no need to clone every time. For additional builds,
         simply use:
          cd nspr; hg pull -u -v; cd ..; cd nss; hg pull -u -v; cd ..;
          cd jss; hg pull -u -v; cd ..
        )

    (b) Alternatively, for upstream builds which use
        the NSPR and NSS installed on the system:

        # mkdir sandbox
        # cd sandbox
        # export USE_INSTALLED_NSPR=1
        # export USE_INSTALLED_NSS=1
        # export PKG_CONFIG_ALLOW_SYSTEM_LIBS=1
        # export PKG_CONFIG_ALLOW_SYSTEM_CFLAGS=1
        # export NSPR_INCLUDE_DIR=`/usr/bin/pkg-config --cflags-only-I nspr | sed 's/-I//'`
        # export NSPR_LIB_DIR=`/usr/bin/pkg-config --libs-only-L nspr | sed 's/-L//'`
        # export NSS_INCLUDE_DIR=`/usr/bin/pkg-config --cflags-only-I nss | sed 's/-I//'`
        # export NSS_LIB_DIR=`/usr/bin/pkg-config --libs-only-L nss | sed 's/-L//'`
        # export XCFLAGS="-g"
        # hg clone https://hg.mozilla.org/projects/jss
        # cd ..

        (There is no need to clone every time. For additional builds,
         simply use:
          cd jss; hg pull -u -v; cd ..
        )


(2) Prepare an interactive shell for building:

    # export JAVA_HOME=/etc/alternatives/java_sdk_1.8.0_openjdk
    # export USE_64=1

    NOTE:  JSS will now attempt to verify whether or not these two
           environment variables have been set (JAVA_HOME is mandatory;
           USE_64 is mandatory on 64-bit platforms when building 64-bit).

    The following steps are optional, and left to the discretion of the user:

        Debug vs. Optimized jar files:

            By default, JSS will be built as a debuggable jar
            (xpclass_dbg.jar - generally recommended for test builds);
            to create an optimized jar (xpclass.jar), set the following
            environment variable:

                # export BUILD_OPT=1

        Beta vs. Non-Beta builds:

            Finally, by default, JSS is not built as a "beta" release (as
            specified in 'org/mozilla/jss/util/jssver.h'):

                #define JSS_BETA     PR_FALSE

            If a "beta" version of JSS is desired, reset this #define (as
            specified in 'org/mozilla/jss/util/jssver.h') to:

                #define JSS_BETA     PR_TRUE


(3) Build JSS

    # cd sandbox/jss
    # make clean all
    # cd ../..

    (or you can run "# script -c 'make clean all' typescript.build")

    NOTE: When build method (1)(a) is being utilized, if nss has not been
          built, it will now automatically be built before jss; if nss has
          already been built, only jss will be built/re-built.


(4) Install JSS on the System (Optional)

    If JSS already exists on the system, run something similar to the
    following command(s):

        # sudo mv /usr/lib/java/jss4.jar /usr/lib/java/jss4.jar.orig

        If the platform is 32-bit Linux:

            # sudo mv /usr/lib/jss/libjss4.so /usr/lib/jss/libjss4.so.orig

        else if the platform is 64-bit Linux:

            # sudo mv /usr/lib64/jss/libjss4.so /usr/lib64/jss/libjss4.so.orig

    If BUILD_OPT is undefined (default Debuggable Jar):

        # sudo cp sandbox/dist/xpclass_dbg.jar /usr/lib/java/jss4.jar

    else if BUILD_OPT is defined (Optimized Jar):

        # sudo cp sandbox/dist/xpclass.jar /usr/lib/java/jss4.jar

    # sudo chown root:root /usr/lib/java/jss4.jar
    # sudo chmod 644 /usr/lib/java/jss4.jar

    # sudo cp sandbox/jss/lib/Linux*.OBJ/libjss4.so /usr/lib64/jss/libjss4.so
    # sudo chown root:root /usr/lib64/jss/libjss4.so
    # sudo chmod 755 /usr/lib64/jss/libjss4.so


(5) Run JSS Tests (Optional, but only if build method (1)(a) was utilized)

    If build method (1)(a) is being utilized, it is possible to run the
    built-in JSS tests:

        # cd sandbox/jss
        # make test_jss
        # cd ../..

        (or you can run "# script -c 'make test_jss' typescript.tests")

    NOTE: This command is currently only available on Linux and Macintosh
          platforms when method (1)(a) has been utilized to build JSS
          since the tests are dependent upon the work area as setup in
          this method; currenty JSS must be built via 'make clean all' before
          execution of this command (e.g. - build is separate from test).


(6) Restoration of non-Test-Only Systems (Optional)

    If step (4) above was run, and the system is being used for purposes
    other than test, the user may wish to restore the original system JSS
    by running the following commands:

        # sudo mv /usr/lib/java/jss4.jar.orig /usr/lib/java/jss4.jar

        If the platform is 32-bit Linux:

            # sudo mv /usr/lib/jss/libjss4.so.orig /usr/lib/jss/libjss4.so

        else if the platform is 64-bit Linux:

            # sudo mv /usr/lib64/jss/libjss4.so.orig /usr/lib64/jss/libjss4.so

        NOTE:  For this procedure, no ownership or permission changes should
               be necessary.


(7) Tagging the Source Code for a Release

    During development, several releases may be made.  Consequently, it is
    good practice to create a "regular tag" to the source code at these
    various points in time using the following format:

        # hg tag -m "message" JSS_<major>_<minor>_YYYYMMDD

        where:  <major> = JSS Major Version Number
                <minor> = JSS Minor Version Number
                YYYY    = 4-digit year (e. g. - 2017)
                MM      = 2-digit month (e. g. - 01, ..., 12)
                DD      = 2-digit day of the month (e. g. - 01, ..., 31)
    
        For example:

            # hg id
            b3e864205ff0+ tip

            # hg tag -m "Added tag JSS_4_4_20170328 for changeset b3e864205ff0" JSS_4_4_20170328

    At the appropriate time, a new major.minor version may be created.  At this
    time, it is important to create a maintenance branch for any future changes
    to the previous major.minor version:

    For example:

        # hg id
        f00f00f00f00+ tip

        # hg branch -m "Created branch JSS_4_4_BRANCH for changeset f00f00f00f00" JSS_4_4_BRANCH


(8) Known Issues

    * Mozilla Bug #1346410 - Load JSS libraries appropriately

    NOTE:  This issue should not occur unless step (4) above was skipped.

    Testing failures were found while working on Bug 1346410 when loading the
    JSS libraries to meet requirements of certain operating systems.  Our
    investigation revealed that due to the nature of the changes made via this
    patch and its interaction with the HMAC Tests (both non-FIPS and FIPS),
    that a failure may be encountered on one or more of the HMAC algorithms
    causing these two tests to fail.  On 64-bit Linux, for example, the
    workaround for this issue is to perform the following steps before
    re-running the tests:

        (a) Install the new JSS builds by executing step (4) above

        (b) Execute the following commands:

            # cd sandbox/jss; make test_jss

    NOTE:  If the system is being used for purposes other than test, the user
           may wish to restore the original JSS by executing step (6) above.