godoc: app engine configuration and updated documentation

Also: Fixed an error message in zip.go.

R=r, dsymonds
CC=golang-dev
https://golang.org/cl/4816053

src/cmd/godoc/appconfig.go

@@ -0,0 +1,19 @@
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// This file contains configuration information used by
+// godoc when running on app engine. Adjust as needed
+// (typically when the .zip file changes).
+
+package main
+
+const (
+	// zipFilename is the name of the .zip file
+	// containing the file system served by godoc.
+	zipFilename = "go.zip"
+
+	// zipGoroot is the path of the goroot directory
+	// in the .zip file.
+	zipGoroot = "/home/username/go"
+)

src/cmd/godoc/appinit.go

@@ -0,0 +1,86 @@
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// To run godoc under app engine, substitute main.go with
+// this file (appinit.go), provide a .zip file containing
+// the file system to serve, and adjust the configuration
+// parameters in appconfig.go accordingly.
+//
+// The current app engine SDK may be based on an older Go
+// release version. To correct for version skew, copy newer
+// packages into the alt directory (e.g. alt/strings) and
+// adjust the imports in the godoc source files (e.g. from
+// `import "strings"` to `import "alt/strings"`). Both old
+// and new packages may be used simultaneously as long as
+// there is no package global state that needs to be shared.
+//
+// The directory structure should look as follows:
+//
+// godoc			// directory containing the app engine app
+//      alt			// alternative packages directory to
+//				//	correct for version skew
+//		strings		// never version of the strings package
+//		...		//
+//	app.yaml		// app engine control file
+//	go.zip			// zip file containing the file system to serve
+//	godoc			// contains godoc sources
+//		appinit.go	// this file instead of godoc/main.go
+//		appconfig.go	// godoc for app engine configuration
+//		...		//
+//
+// To run app the engine emulator locally:
+//
+//	dev_appserver.py -a 0 godoc
+//
+// godoc is the top-level "goroot" directory.
+// The godoc home page is served at: <hostname>:8080 and localhost:8080.
+
+package main
+
+import (
+	"alt/archive/zip"
+	"http"
+	"log"
+	"os"
+)
+
+func serveError(w http.ResponseWriter, r *http.Request, relpath string, err os.Error) {
+	contents := applyTemplate(errorHTML, "errorHTML", err) // err may contain an absolute path!
+	w.WriteHeader(http.StatusNotFound)
+	servePage(w, "File "+relpath, "", "", contents)
+}
+
+func init() {
+	log.Println("initializing godoc ...")
+	*goroot = path.Join("/", zipGoroot) // fsHttp paths are relative to '/'
+
+	// read .zip file and set up file systems
+	const zipfile = zipFilename
+	rc, err := zip.OpenReader(zipfile)
+	if err != nil {
+		log.Fatalf("%s: %s\n", zipfile, err)
+	}
+	fs = NewZipFS(rc)
+	fsHttp = NewHttpZipFS(rc, *goroot)
+
+	// initialize http handlers
+	initHandlers()
+	readTemplates()
+	registerPublicHandlers(http.DefaultServeMux)
+
+	// initialize default directory tree with corresponding timestamp.
+	initFSTree()
+
+	// initialize directory trees for user-defined file systems (-path flag).
+	initDirTrees()
+
+	// create search index
+	// TODO(gri) Disabled for now as it takes too long. Find a solution for this.
+	/*
+		*indexEnabled = true
+		go indexer()
+	*/
+
+	log.Println("godoc initialization complete")
+}

src/cmd/godoc/doc.go

@@ -97,10 +97,9 @@ may be provided with the -filter flag; if it exists, only directories
 on those paths are considered. If -filter_minutes is set, the filter_file is
 updated regularly by walking the entire directory tree.
 
-When godoc runs as a web server, it creates a search index from all .go files
+When godoc runs as a web server and -index is set, a search index is maintained.
-under -goroot (excluding files starting with .). The index is created at startup
+The index is created at startup and is automatically updated every time the
-and is automatically updated every time the -sync command terminates with exit
+-sync command terminates with exit status 0, indicating that files have changed.
-status 0, indicating that files have changed.
 
 If the sync exit status is 1, godoc assumes that it succeeded without errors
 but that no files changed; the index is not updated in this case.
@@ -109,5 +108,23 @@ In all other cases, sync is assumed to have failed and godoc backs off running
 sync exponentially (up to 1 day). As soon as sync succeeds again (exit status 0
 or 1), the normal sync rhythm is re-established.
 
+The index contains both identifier and full text search information (searchable
+via regular expressions). The maximum number of full text search results shown
+can be set with the -maxresults flag; if set to 0, no full text results are
+shown, and only an identifier index but no full text search index is created.
+
+By default, godoc serves files from the file system of the underlying OS.
+Instead, a .zip file may be provided via the -zip flag, which contains
+the file system to serve. The file paths stored in the .zip file must use
+slash ('/') as path separator; and they must be unrooted. $GOROOT (or -goroot)
+must be set to the .zip file directory path containing the Go root directory.
+For instance, for a .zip file created by the command:
+
+	zip go.zip $HOME/go
+
+one may run godoc as follows:
+
+	godoc -http=:6060 -zip=go.zip -goroot=$HOME/go
+
 */
 package documentation

src/cmd/godoc/main.go

@@ -38,6 +38,7 @@ import (
 	"io"
 	"log"
 	"os"
+	"path"
 	"path/filepath"
 	"regexp"
 	"runtime"
@@ -228,23 +229,22 @@ func main() {
 		log.Fatalf("negative tabwidth %d", *tabwidth)
 	}
 
-	// Clean goroot: normalize path separator.
-	*goroot = filepath.Clean(*goroot)
-
 	// Determine file system to use.
 	// TODO(gri) - fs and fsHttp should really be the same. Try to unify.
 	//           - fsHttp doesn't need to be set up in command-line mode,
 	//             same is true for the http handlers in initHandlers.
 	if *zipfile == "" {
 		// use file system of underlying OS
+		*goroot = filepath.Clean(*goroot) // normalize path separator
 		fs = OS
 		fsHttp = http.Dir(*goroot)
 	} else {
-		// use file system specified via .zip file
+		// use file system specified via .zip file (path separator must be '/')
 		rc, err := zip.OpenReader(*zipfile)
 		if err != nil {
 			log.Fatalf("%s: %s\n", *zipfile, err)
 		}
+		*goroot = path.Join("/", *goroot) // fsHttp paths are relative to '/'
 		fs = NewZipFS(rc)
 		fsHttp = NewHttpZipFS(rc, *goroot)
 	}

src/cmd/godoc/zip.go

@@ -83,7 +83,8 @@ func zipPath(name string) string {
 func (fs *zipFS) stat(abspath string) (int, zipFI, os.Error) {
 	i, exact := fs.list.lookup(abspath)
 	if i < 0 {
-		return -1, zipFI{}, fmt.Errorf("file not found: %s", abspath)
+		// abspath has leading '/' stripped - print it explicitly
+		return -1, zipFI{}, fmt.Errorf("file not found: /%s", abspath)
 	}
 	_, name := path.Split(abspath)
 	var file *zip.File