Derby
  1. Derby
  2. DERBY-4501

CLASSPATH scripts do not work as defined in Getting Started in Derby Guide

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.5.3.0
    • Fix Version/s: 10.6.1.0
    • Component/s: Documentation
    • Labels:
      None
    • Environment:
      Unix platforms
    • Urgency:
      Low

      Description

      On pages 13 and 14 of the 'Getting Started in Derby Guide', there are 3
      scripts referenced that can be used to set the CLASSPATH environment
      variable. setEmbeddedCP, setNetworkServerCP, & setNetworkClientCP. The
      documentation indicates that the appropriate script should be run
      depending on your needs.

      Running the scripts like any other script does not work.

      When a script is run, it launches a new shell for that script. The
      CLASSPATH is set within that shell. Once the script is complete, that
      shell exits and you are returned to your shell. The CLASSPATH is only
      changed for the shell that the script was running in. The CLASSPATH in
      your shell is unchanged.

      $ $

      {DERBY_HOME}/bin/setNetworkClientCP
      Will result in your CLASSPATH being unchanged.

      In order for CLASSPATH in your shell to be updated, you have to run the
      script from within your shell (not launch a new shell). This is done by
      'sourcing' the script.

      $ . ${DERBY_HOME}

      /bin/setNetworkClientCP
      Will run the script within your shell resulting in your CLASSPATH being
      updated.

      The documentation is not clear on this.

      Bug DERBY-4500 has been opened to address a related issue that will arise if/when the documentation is updated to reflect that the scripts should be sourced rather than run.

      1. tgs26250.html
        7 kB
        Bryan Pendleton
      2. tgs26250.html
        8 kB
        Bryan Pendleton
      3. tgs26250.html
        8 kB
        Bryan Pendleton
      4. docs.diff
        3 kB
        Bryan Pendleton
      5. docs.diff
        3 kB
        Bryan Pendleton
      6. docs.diff
        3 kB
        Bryan Pendleton

        Activity

        Hide
        Knut Anders Hatlen added a comment -

        [bulk update] Close all resolved issues that haven't been updated for more than one year.

        Show
        Knut Anders Hatlen added a comment - [bulk update] Close all resolved issues that haven't been updated for more than one year.
        Hide
        Bryan Pendleton added a comment -

        Updated the docs and committed to the docs trunk as revision 904693.

        Show
        Bryan Pendleton added a comment - Updated the docs and committed to the docs trunk as revision 904693.
        Hide
        Kim Haase added a comment -

        Thanks, Bryan – this looks good now. +1 from this end.

        Show
        Kim Haase added a comment - Thanks, Bryan – this looks good now. +1 from this end.
        Hide
        Bryan Pendleton added a comment -

        OK, here's another try at the patch, and the corresponding HTML-formatted page.

        I feel that the docs are significantly better than they were before, and they now
        address the issues raised in the description of this problem, as well as several
        related issues raised during the discussion. Thanks to all for the contributions!

        Show
        Bryan Pendleton added a comment - OK, here's another try at the patch, and the corresponding HTML-formatted page. I feel that the docs are significantly better than they were before, and they now address the issues raised in the description of this problem, as well as several related issues raised during the discussion. Thanks to all for the contributions!
        Hide
        Kim Haase added a comment -

        I agree with Dag. Helping with the shells that the scripts work with is fine. Users don't really need the scripts – starting the tools using the java command as described in the Getting Started tasks works fine.

        Show
        Kim Haase added a comment - I agree with Dag. Helping with the shells that the scripts work with is fine. Users don't really need the scripts – starting the tools using the java command as described in the Getting Started tasks works fine.
        Hide
        Dag H. Wanvik added a comment -

        I think updating the docs as you suggest is OK for now, Bryan.

        Show
        Dag H. Wanvik added a comment - I think updating the docs as you suggest is OK for now, Bryan.
        Hide
        Bryan Pendleton added a comment -

        Thanks Kim and Dag for the good suggestions and extra testing.

        I feel that we should treat the issue of changing the scripts to run in more UNIX shells as a separate
        enhancement, and as part of this change we should just try to document the current scripts as
        well as we can.

        Unfortunately, on my system (RedHat Linux-based), the current scripts work fine when running /bin/sh,
        which perhaps is just another way of saying that /bin/sh on my system is actually BASH, not Bourne shell,
        so I don't really have access to an environment where I can work on improving the scripts.

        But if others want to work on the scripts to improve their portability to other shells, I think that would be wonderful!

        In the meantime, I'll update the docs to incorporate the good suggestions above, and will also add
        a sentence along the lines of:

        The UNIX shell scripts are known to run successfully in the Bash shell, and you may need to
        modify them slightly if you are using a different UNIX shell.

        I think I should probably reword the information that I added about the Bourne shell in the previous patch,
        because I can't tell if it's correct or not, since I don't think I have a true Bourne shell to try. Instead, I'll
        label the alternate sections as "using the "dot" command" and "using the "source" command".

        Show
        Bryan Pendleton added a comment - Thanks Kim and Dag for the good suggestions and extra testing. I feel that we should treat the issue of changing the scripts to run in more UNIX shells as a separate enhancement, and as part of this change we should just try to document the current scripts as well as we can. Unfortunately, on my system (RedHat Linux-based), the current scripts work fine when running /bin/sh, which perhaps is just another way of saying that /bin/sh on my system is actually BASH, not Bourne shell, so I don't really have access to an environment where I can work on improving the scripts. But if others want to work on the scripts to improve their portability to other shells, I think that would be wonderful! In the meantime, I'll update the docs to incorporate the good suggestions above, and will also add a sentence along the lines of: The UNIX shell scripts are known to run successfully in the Bash shell, and you may need to modify them slightly if you are using a different UNIX shell. I think I should probably reword the information that I added about the Bourne shell in the previous patch, because I can't tell if it's correct or not, since I don't think I have a true Bourne shell to try. Instead, I'll label the alternate sections as "using the "dot" command" and "using the "source" command".
        Hide
        Dag H. Wanvik added a comment -

        Actually, we don't provide a csh/tcsh sourcable setting script right now. We may consider adding that, though.

        As for your second attempt, I notice that the current UNIX shell script uses the bash syntax for combined setting and exporting an environment variable, i.e.

        export CLASSPATH= .....

        In a classic Bourne shell, this is not allowed, one needs to write this in two statements:

        CLASSPATH=....
        export CLASSPATH

        which also works in bash, btw. So, for maximum usability I suggest we use the latter form.
        The scripts also contain a misleading "bang" header: "#!/bin/sh" indicating Borne shell syntax,
        when the syntax is reall bash. But the "bang" header should probably omitted anyway, since the script is not meant for running but for sourcing?

        Do the docs call for bash or just sh (Borne shell)?

        Show
        Dag H. Wanvik added a comment - Actually, we don't provide a csh/tcsh sourcable setting script right now. We may consider adding that, though. As for your second attempt, I notice that the current UNIX shell script uses the bash syntax for combined setting and exporting an environment variable, i.e. export CLASSPATH= ..... In a classic Bourne shell, this is not allowed, one needs to write this in two statements: CLASSPATH=.... export CLASSPATH which also works in bash, btw. So, for maximum usability I suggest we use the latter form. The scripts also contain a misleading "bang" header: "#!/bin/sh" indicating Borne shell syntax, when the syntax is reall bash. But the "bang" header should probably omitted anyway, since the script is not meant for running but for sourcing? Do the docs call for bash or just sh (Borne shell)?
        Hide
        Kim Haase added a comment -

        This is very useful info to have – thanks, Bryan.

        I have a couple of language suggestions –

        Being kind of a stickler about "differently than" I would suggest changing the sentence to either

        "Note that these scripts behave slightly differently on UNIX systems and on Windows systems."

        or

        "Note that these scripts behave slightly differently on UNIX systems from the way they behave on Windows systems."

        Also, the long sentence starting with "Otherwise" might better be broken into separate sentences – perhaps the UNIX and Windows info can be in separate paragraphs.

        "On UNIX systems, you need to use the "dot" or "source" command to ensure that the script is run in the calling shell's environment. Otherwise, when a script is run, it launches a new shell for that script. The CLASSPATH is set within that shell. Once the script is complete, that shell exits and you are returned to your shell. The CLASSPATH is changed only for the shell that the script was running in. The CLASSPATH in your shell is unchanged."

        That said, I happen to be running in a C shell on Solaris, and I can't make the scripts work at all, even if I switch to a Bourne shell. Neither source nor dot seems to work. This may be of no concern to anybody, things being how they are ...

        I already have the classpath set, so that I can build the Derby docs – you probably do too.

        jdench 49 =>setenv DERBY_HOME /home/chaase/db-derby-10.5.3.0-bin
        jdench 50 =>echo $CLASSPATH
        .:./lib/fop.jar:./lib/avalon-framework-cvs-20020806.jar:./lib/batik.jar
        jdench 51 =>echo $DERBY_HOME
        /home/chaase/db-derby-10.5.3.0-bin
        jdench 52 =>source $DERBY_HOME/bin/setEmbeddedCP
        Missing ]
        jdench 53 =>. $DERBY_HOME/bin/setEmbeddedCP
        /home/chaase/javaee6-sdk/glassfish/bin/.: Permission denied
        jdench 54 =>echo $CLASSPATH
        .:./lib/fop.jar:./lib/avalon-framework-cvs-20020806.jar:./lib/batik.jar

        jdench 56 =>/bin/sh
        $ echo $CLASSPATH
        .:./lib/fop.jar:./lib/avalon-framework-cvs-20020806.jar:./lib/batik.jar
        $ echo $DERBY_HOME
        /home/chaase/db-derby-10.5.3.0-bin
        $ . $DERBY_HOME/bin/setEmbeddedCP
        CLASSPATH=/home/chaase/db-derby-10.5.3.0-bin/lib/derby.jar:/home/chaase/db-derby-10.5.3.0-bin/lib/derbytools.jar:.:./lib/fop.jar:./lib/avalon-framework-cvs-20020806.jar:./lib/batik.jar: is not an identifier
        $ echo $CLASSPATH
        .:./lib/fop.jar:./lib/avalon-framework-cvs-20020806.jar:./lib/batik.jar

        Show
        Kim Haase added a comment - This is very useful info to have – thanks, Bryan. I have a couple of language suggestions – Being kind of a stickler about "differently than" I would suggest changing the sentence to either "Note that these scripts behave slightly differently on UNIX systems and on Windows systems." or "Note that these scripts behave slightly differently on UNIX systems from the way they behave on Windows systems." Also, the long sentence starting with "Otherwise" might better be broken into separate sentences – perhaps the UNIX and Windows info can be in separate paragraphs. "On UNIX systems, you need to use the "dot" or "source" command to ensure that the script is run in the calling shell's environment. Otherwise, when a script is run, it launches a new shell for that script. The CLASSPATH is set within that shell. Once the script is complete, that shell exits and you are returned to your shell. The CLASSPATH is changed only for the shell that the script was running in. The CLASSPATH in your shell is unchanged." That said, I happen to be running in a C shell on Solaris, and I can't make the scripts work at all, even if I switch to a Bourne shell. Neither source nor dot seems to work. This may be of no concern to anybody, things being how they are ... I already have the classpath set, so that I can build the Derby docs – you probably do too. jdench 49 =>setenv DERBY_HOME /home/chaase/db-derby-10.5.3.0-bin jdench 50 =>echo $CLASSPATH .:./lib/fop.jar:./lib/avalon-framework-cvs-20020806.jar:./lib/batik.jar jdench 51 =>echo $DERBY_HOME /home/chaase/db-derby-10.5.3.0-bin jdench 52 =>source $DERBY_HOME/bin/setEmbeddedCP Missing ] jdench 53 =>. $DERBY_HOME/bin/setEmbeddedCP /home/chaase/javaee6-sdk/glassfish/bin/.: Permission denied jdench 54 =>echo $CLASSPATH .:./lib/fop.jar:./lib/avalon-framework-cvs-20020806.jar:./lib/batik.jar jdench 56 =>/bin/sh $ echo $CLASSPATH .:./lib/fop.jar:./lib/avalon-framework-cvs-20020806.jar:./lib/batik.jar $ echo $DERBY_HOME /home/chaase/db-derby-10.5.3.0-bin $ . $DERBY_HOME/bin/setEmbeddedCP CLASSPATH=/home/chaase/db-derby-10.5.3.0-bin/lib/derby.jar:/home/chaase/db-derby-10.5.3.0-bin/lib/derbytools.jar:.:./lib/fop.jar:./lib/avalon-framework-cvs-20020806.jar:./lib/batik.jar: is not an identifier $ echo $CLASSPATH .:./lib/fop.jar:./lib/avalon-framework-cvs-20020806.jar:./lib/batik.jar
        Hide
        Bryan Pendleton added a comment -

        Thanks Dag, I think that is a good suggestion. I took another stab at the
        page, including information about both shell styles.

        Show
        Bryan Pendleton added a comment - Thanks Dag, I think that is a good suggestion. I took another stab at the page, including information about both shell styles.
        Hide
        Dag H. Wanvik added a comment -

        Thanks for tackling this, Bryan! Looks like a clear improvement to me.
        Instead of "dot", you might consider "dot" or "source"; bash allows both use of the dot-syntax and the source keyword.
        As for the example, do you presume that the user has done a cd to the directory containing the scripts or added it to the PATH environement variable? Would it perhaps be even more helpful to write something like this:

        UNIX Bourne shell:

        > DERBY_HOME=/derby/db-derby-10.5.3.0-bin
        > . $DERBY_HOME/bin/setEmbeddedCP

        or with Bash:

        > DERBY_HOME=/derby/db-derby-10.5.3.0-bin
        > source $DERBY_HOME/bin/setEmbeddedCP

        Show
        Dag H. Wanvik added a comment - Thanks for tackling this, Bryan! Looks like a clear improvement to me. Instead of "dot", you might consider "dot" or "source"; bash allows both use of the dot-syntax and the source keyword. As for the example, do you presume that the user has done a cd to the directory containing the scripts or added it to the PATH environement variable? Would it perhaps be even more helpful to write something like this: UNIX Bourne shell: > DERBY_HOME=/derby/db-derby-10.5.3.0-bin > . $DERBY_HOME/bin/setEmbeddedCP or with Bash: > DERBY_HOME=/derby/db-derby-10.5.3.0-bin > source $DERBY_HOME/bin/setEmbeddedCP
        Hide
        Bryan Pendleton added a comment -

        I agree that the different behavior of these scripts on Windows versus Unix/Linux
        systems can be quite confusing. I tried to improve the documentation to
        make this more clear.

        Attached is a docs patch proposal ('docs.diff') and an HTML-formatted
        version of the relevant page from the Getting Started guide.

        I'm interested in whether people feel this makes the behavior more clear.

        Show
        Bryan Pendleton added a comment - I agree that the different behavior of these scripts on Windows versus Unix/Linux systems can be quite confusing. I tried to improve the documentation to make this more clear. Attached is a docs patch proposal ('docs.diff') and an HTML-formatted version of the relevant page from the Getting Started guide. I'm interested in whether people feel this makes the behavior more clear.

          People

          • Assignee:
            Bryan Pendleton
            Reporter:
            John Storta Jr.
          • Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development