Unclear INSTALL doc + suggested changes

[John Watkins]

[This is my first attempt to report bugs here. Any suggestons for future bug reports would be appreciated.]

sbcl --version => SBCL 1.1.10.6-1540c1c
uname -a => Linux pelican 3.2.0-4-amd64 #1 SMP Debian 3.2.46-1 x86_64 GNU/Linux

I attempted to install SBCL using the instructions in sbcl/INSTALL. It failed trying to open the output/prefix.def file. In fact the file was not there, nor was the directory. The solution is outlined in the changes I am proposing to the instructions in the INSTALL file.

I am proposing the following three changes to the INSTALL doc found under sbcl/ directory. I am making this suggestion because my install failed untill I figured this out:

1. "Section 1.1 Quick Start" would be better titled "Section 1.1 Quick Start and Installation" since both topics are in fact the discussed in section 1.1.

2. The frist sentence of Section 1.1 says, " To run SBCL without installing it, from the top of binary distribution
  directory: $ sh run-sbcl.sh"

It should read, " To run SBCL without installing it or to install SBCL, from the top of binary distribution
  directory: $ sh run-sbcl.sh" This change is necessary since the origianl line implies that the command "sh run-sbcl.sh" needs be run if you do not want to install SBCL. In fact you cannot install SBCL with the subsequent instruction in this section without running this script first.

3. The next sentence reads, " The following command installs SBCL and related documentation under
  the "/usr/local" directory ..." This is not correct. The documenatioan will note be installed. Prior to this sentence, a line should be added that says, in effect, "If you want the documentation included in your installation switch to the doc directory [i.e. cd /doc] and run the $sh make-doc.sh. When this is completed return to the /sbcl directory [i.e. cd .

My suggestions are not the only approach to making the INSTALL work as outlined. I am suggesting these changes because I believe they are the simplest to implement.

[Stas Boukarev (stassats)]

I don't understand, you don't need to run ./run-sbcl.sh before installing.

[John Watkins (jcw)]

That is exactly what I thought when I read the second line of the instructions for section 1.1. So I skipped running the ./run-sbcl.sh step. Instead I ran INSTALL_ROOT=/usr/local sh install.sh as root as the second sentence insturcted. But the shell script failed looking for the ouput/prefix.def. When I looked in the sbcl/ directory their was on output directory.

So I ran the ./run-sbcl.sh to see if I had somehow improperly copied the files using git. SBCL ran fine. Then I looked at the directories and found the missing diorectory and file. I ran them INSTALL script as directed and everyhing installed.

My installation was by someone unfamiliary with the SBCL installatin. So this report is from somone without any notions of what is expected. I simply read the instructions for Quick Start in Section 1.1 quite literaly. My result was an install failure.

[John Watkins (jcw)]

Just to clarify. After git was run but before I did anything, their was no output/ directory.

It was not until I ran ./run-sbcl.sh that the missing directory and files were created. Only then could I porceed with the INSTALL as outlined in section 1.1

The changes I suggest are not necesarily the best solution. They are simply what worked for me.

[Stas Boukarev (stassats)]

You are reading the wrong section, 1.1 Quickstart is under 1. BINARY DISTRIBUTION, and you've got a source distribution, which is described in the section 2. Moreover, ./run-sbcl.sh won't create output/, ./make.sh will.

[John Watkins (jcw)]

On 08/12/2013 10:52 PM, Stas Boukarev wrote:
> You are reading the wrong section, 1.1 Quickstart is under 1. BINARY
> DISTRIBUTION, and you've got a source distribution, which is described
> in the section 2. Moreover, ./run-sbcl.sh won't create output/,
> ./make.sh will.
>
> ** Changed in: sbcl
> Status: New => Invalid
>
How does a new user tell if they have source or binary distribution?

[Stas Boukarev (stassats)]

Presumably the user is conscious when downloading one or the other.

[Christophe Rhodes (csr21-cantab)]

John Watkins <email address hidden> writes:

> On 08/12/2013 10:52 PM, Stas Boukarev wrote:
>> You are reading the wrong section, 1.1 Quickstart is under 1. BINARY
>> DISTRIBUTION, and you've got a source distribution, which is described
>> in the section 2. Moreover, ./run-sbcl.sh won't create output/,
>> ./make.sh will.
>>
>> ** Changed in: sbcl
>> Status: New => Invalid
>>
> How does a new user tell if they have source or binary distribution?

That new user will (presumably) have downloaded something from
<http://www.sbcl.org/platform-table.html>. On that page, all the binary
distributions have the string "binary" in their name, and the source
distribution has the string "source" in its name. (Or they might have
downloaded something from sourceforge directly, in which case the same
naming convention applies).

If that's not how you got whatever it is you got, can you tell us where
you got it from?

Christophe

[Paul Khuong (pvk)]

The original report hints the source tree was cloned via git. I'll see about adding extra clarifications in 1.1… a lot of people seem to skip section headers.

[John Watkins (jcw)]

On 08/13/2013 08:33 AM, Stas Boukarev wrote:
> Presumably the user is conscious when downloading one or the other.
>
Well, in my experience it is best not to make assumptions about others
and in particular not about new ignorant users.

Here is what I did. I went to the SBCL page
http://www.sbcl.org/platform-table.html. The page provides a link to
download, "the most recent version of SBCL is 1.1.10..." Initially I
used the git command in that first section to download the files.

I just now downloaded the tar file sbcl-1.1.10-source.tar.bz2. The name
clearly states it 'source." And, as has been pointed out I can download
a binary version for Linux as well. I just tried that as well.

In retrospect I suppose the development version is released as source
files only. But it was not explicit and I violated my on experience by
making an assumption. I assumed the binaries for the version would be
included in the download from SourceForge.

I guess I'll try to remove the installation I have done and start from
scratch. I've probably mucked it up a bit. Uninstalling can be interesting

BTW Thanks again for the help.

John

[Stas Boukarev (stassats)]

It says:
Source: sbcl-1.1.10-source.tar.bz2

The development version is available from git:
git clone git://git.code.sf.net/p/sbcl/sbcl

Binaries:
...

so git is clearly for sources. And I have never seen version control systems used for distributing binaries. If that's not enough of a clue, then I don't see why more detailed information in the INSTALL file wouldn't be ignored just as well.

Changed to confirmed, since your 3 point about documentation installation is valid.

[Christophe Rhodes (csr21-cantab)]

Stas Boukarev <email address hidden> writes:

> so git is clearly for sources. And I have never seen version control
> systems used for distributing binaries.

For information: Clozure uses subversion to distribute binaries of CCL.

Christophe

[John Watkins (jcw)]

Yep you are correct. My mistake. i apologize for the noise.

FYI I worked for a rather large software company in the SF Bay area. At
least one division kept binaries in their source contorl system. The
reasoning was they would have copies of the exact binaries shipped to
customers. It was in the words of the VP who pushed for it "a way to
avoid differences in the test environment computer systems" that
inevitably crept in.

On 08/14/2013 12:34 AM, Stas Boukarev wrote:
> It says:
> Source: sbcl-1.1.10-source.tar.bz2
>
> The development version is available from git:
> git clone git://git.code.sf.net/p/sbcl/sbcl
>
> Binaries:
> ...
>
> so git is clearly for sources. And I have never seen version control
> systems used for distributing binaries. If that's not enough of a clue,
> then I don't see why more detailed information in the INSTALL file
> wouldn't be ignored just as well.
>
> Changed to confirmed, since your 3 point about documentation
> installation is valid.
>
> ** Changed in: sbcl
> Status: Invalid => Confirmed
>
> ** Changed in: sbcl
> Importance: Undecided => Low
>