From bb545d48b3d2ef165112f45ea4fad594e9a791cb Mon Sep 17 00:00:00 2001 From: Will Duquette Date: Sat, 30 Aug 2014 10:57:06 -0700 Subject: [PATCH] Updated docs --- README.md | 67 +++++++++++++++++++++++++++++++++---------------- TODO.md | 1 + docs/BUILD.md | 29 +++++++++++++++------ docs/INSTALL.md | 57 ++++++++++++++++++----------------------- 4 files changed, 93 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 32dc565..750cae4 100644 --- a/README.md +++ b/README.md @@ -4,17 +4,23 @@ Quill is a build tool for Tcl/Tk projects, inspired by [Leiningen](http://leiningen.org). It is intended to: * Create new skeleton project trees. +* Run test suites +* Format HTML documentation * Manage dependencies * External and internal -* Run tests +* Execute your project +* Execute arbitrary scripts in the context of your project's code base * Build deployment targets: * Standalone executables ("starpacks") * Lightweight executables ("starkits") - * Reusable packages (teapot modules, .tm or .zip) + * Reusable packages (teapot .zip modules) * Make it easy to build and deploy Tcl applications and libraries. -* Support formatted HTML documentation * Run cross-platform (Windows, OS X, Linux) +As such, it is intended to reduce the ancillary costs of defining and +deploying a Tcl package or executable to as close to zero as possible, by +automating everything but the actual writing of the code and documentation. + ## Building and Installation To install Quill, see [docs/INSTALL.md](./docs/INSTALL.md). @@ -24,10 +30,10 @@ To build Quill from scratch, see [docs/BUILD.md](./docs/BUILD.md). ## Basic Use Case -Assuming you have ActiveTcl 8.6.1 or later installed, with the installation's +Assuming you have ActiveTcl 8.5 or later installed, with the installation's `tclsh` on your path, you should be able to do the following: -**Download and install `quill.kit` in your ~/bin directory (or wherever).** +**Download and install `quill.exe` in your ~/bin directory (or wherever).** See [docs/INSTALL.md](./docs/INSTALL.md). **Create a new skeleton project tree:** @@ -82,6 +88,13 @@ $ quill shell ... (Invokes Tkcon; does not run the application's "main" proc) ``` +** Install your application and libraries for local use:** + +``` +$ quill install +... (Copies the executable to your ~/bin, and libraries to your teapot) +``` + ## Other Features Quill can also build library packages and install them into your local @@ -94,27 +107,37 @@ Then, you can add `require` statements to your `project.quill` file the required packages into your local teapot when you execute `quill deps update`. +Finally, if you define a distribution in `project.quill`, Quill will build +distribution .zip file for you. + See the [quill(5)](./docs/man5/quill.manpage) man page for information about the contents of the `project.quill` file, and enter `quill help` at the command line for help on Quill and its subcommands. -## Assumptions +## Dependencies -At present, Quill relies heavily on ActiveState's package repository -tool-chain, and particularly on "teacup" (delivered with ActiveTcl) -and "tclapp" (delivered as part of TclDevKit). In particular, Quill -assumes the following: +How much Quill can do for you depends on what ancillary tools you have +installed. You will need a Tcl interpreter at the very least. -* ActiveTcl 8.6.1 or later is installed on the system. -* ActiveTcl is on the path, and can be run as "tclsh" at the - command line -* For building executables, TclDevKit 5.0 or later is installed on - the system, and the "tclapp" tool can be run as "tclapp" at the - command line. -* For Unix-based systems, including Mac OS X, it is assumed for - certain operations that either ActiveTcl is installed in the - user's home directory or the user has access to the "sudo" - command. +With just an arbitrary Tcl interpreter, Quill can: + +* Create new project trees for you. +* Run your tests +* Format your documentation +* Make it easier to run your code, either from the system command line or + from an interactive Tcl shell. +* Create distribution .zip files. + +With [ActiveTcl](http://www.activestate.com/activetcl), Quill can: + +* Manage external dependencies, pulling packages from ActiveState's + teapot repository and keeping them up to date in your environment. + +With [TclDevKit 5.0](http://www.activestate.com/tcl-dev-kit), Quill can: + +* Build standalone executables for Linux, OS X, and Windows +* Build libraries as teapot packages, for installation into a local + teapot repository. ## Ways to Help @@ -139,6 +162,8 @@ with that is also welcome. ## Acknowledgements Thanks to the following people who have contributed bug reports, patches, -or ideas to Quill: +or ideas to Quill, or helped in other ways: * Stephan Effelsberg +* Andreas Kupries + diff --git a/TODO.md b/TODO.md index 2be1cf1..67a597d 100644 --- a/TODO.md +++ b/TODO.md @@ -4,6 +4,7 @@ This is the official list of work to be done. # Next +* Fix the distributions in project.quill; they contain different things. * quill new lib * Update release docs. * Building exes: diff --git a/docs/BUILD.md b/docs/BUILD.md index ab0cf24..1b8c4b1 100644 --- a/docs/BUILD.md +++ b/docs/BUILD.md @@ -33,10 +33,14 @@ Next, verify that it has the tools it needs. It should be able to find `tclsh`, `teacup`, `tclapp`: ``` -$ ./bin/quill.tcl version -... (Displays version and helper tools) +$ ./bin/quill.tcl env +... (Displays its view of the environment, including the locations of all + and helper tools) ``` +If necessary, you can use the `quill config` tool to point Quill at the +required tools. + Next, verify that your local teapot is set up properly. It needs to be writable by the user. To find out, use `quill.tcl teapot`. @@ -57,8 +61,10 @@ or $ sudo teacup update-self ``` -Next, you will need Snit 2.3 and texutil::expander 1.3.1 in your local -teapot (they might already be there). To find out, execute: +Next, you will need to have several packages present in your local +teapot--Snit 2.3 and texutil::expander 1.3.1 to begin with, and you +can see the whole list in `~/github/tcl-quill/project.kite`. +(Some of them might already be there). To find out, execute: ``` $ ./bin/quill.tcl deps @@ -70,8 +76,16 @@ If necessary, you can acquire the required packages as follows: $ ./bin/quill.tcl deps update ``` +Next, you can build Quill's documentation: + +``` +$ ./bin/quill.tcl docs +``` + Next, you are ready to build Quill as a standalone executable for your -platform +platform. This also builds Quill's infrastructure library as a reusable +package; see the `docs/` directory for the man pages. + ``` $ ./bin/quill.tcl build @@ -83,6 +97,7 @@ And then, it can be installed for use on your system: $ ./bin/quill install ``` -This copies `./bin/quill` (or `./bin/quill.exe`) to `~/bin/quill`, which -it assumes is on the PATH. +This copies `./bin/quill-{platform}` (or `./bin/quill-{platform}.exe`) +to `~/bin/`, which is assumed to be on the path. It also installs Quill's +infrastructure library into your local teapot for your use. diff --git a/docs/INSTALL.md b/docs/INSTALL.md index fc1c947..d035d51 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -1,45 +1,36 @@ # Installing Quill -## Dependencies +To use Quill for your own projects, you can build Quill from scratch +(see [BUILD.md]) or you can download the distribution file for your +platform from the +[Quill Release Page at GitHub](https://github.com/wduquette/tcl-quill/releases). +This file explains how to install the distribution. -In principle, Quill could be used with any installation of Tcl 8.4 or later. -At present, however, Quill requires some version of ActiveTcl, because of -ActiveTcl's support for "teapot" repositories). - -Further, in order to build executables and libraries for deployment -Quill currently relies on TclDevKit 5. - -These requirements may be relaxed over time; for example, Quill could -in principle support FreeWrap. - -## Installation - -1. Install ActiveTcl 8.4 or later on your development machine. Make - sure that `tclsh` at your command shell of choice invokes - this version of Tcl. - -2. To build executables and libraries for deployment, install - TclDevKit 5.1 so that the `tclapp` and `teapot-pkg` executables - are on your PATH. (Note: Quill can do quite a lot for you even - without TDK installed.) - -3. Download the Quill distribution for your platform. It contains the - following: +1. Download the Quill distribution for your platform, and unzip it. It + contains the following: * `README.md` - * `bin\quill` of `bin\quill.exe` + * `bin\quill-{platform}` or `bin\quill-windows.exe` * `docs\index.html` * `docs\...` + * package-quill-{version}-tcl.zip + +2. Copy the executable from `bin/` to your `~/bin` directory (or wherever + you prefer), renaming it to `quill` or `quill.exe`. + +3. Put the documentation somewhere you can find it, and bookmark + `docs/index.html`. + +4. If desired, install the [quill(n) package](mann/index.html) into your + local teapot. -4. Copy `bin\quill` to your ~/bin directory (or wherever), and make sure it - is marked executable. + $ teacup install package-quill-{version}-tcl.zip -5. Put the documentation somewhere where you can find it. +5. You should now be able to enter these commands: -6. You should now be able to enter the command + $ quill help + $ quill env - `$ quill version` + etc. - This will tell you which version of Quill you are running, and what - helper commands (e.g., `tclsh`, `teacup`, etc.) it has found and will - use. +See the README.md file for more on Quill's capabilities.