tcl-hacks

Check-in [b7067b3f66]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:seperate tclenv.txt from tipple.txt, document some more
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:b7067b3f66e1cfc49f0ba3a87216e1d3a11ce4d0
User & Date: aspect 2018-05-30 10:57:18
Context
2018-06-05
14:22
improve help, adjust some tclenv.txt, stub some stuff check-in: fab3e764ea user: aspect tags: trunk
2018-05-30
10:57
seperate tclenv.txt from tipple.txt, document some more check-in: b7067b3f66 user: aspect tags: trunk
10:26
use-cases and more readme check-in: 6f520aa71c user: aspect tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to tipple/README.md.

9
10
11
12
13
14
15
16
17

18
19
20
21
22
23
24
..
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
..
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
...
137
138
139
140
141
142
143










144
145
146
147
148
149
150
...
159
160
161
162
163
164
165

166
167
168
169
170
171
  * no reliance on any packages not shipped with the core.  `sqlite3` only possible exception
 * access packages from git/fossil repos and teapot
 * use a simple requirements txt format
 * easily consume sensibly-structured source repos without further work on the author's part

Requirements:

 * a unix-like environment
 * Tcl 8.6+

 * any of `curl`, `wget`, `fetch`
 * for installing from repos, `git`, `fossil`

Non-goals:

 * building extensions from source.  Those can come from a teapot
 * doing more than the 80% necessary to bootstrap newbies
................................................................................
 * a fossil or git repository


## Filesystem

Tipple creates a project directory consisting of:

    bin/        -- executables
    lib/        -- pkgIndex.tcl style packages
    modules/    -- .tm style modules
    bin/activate    -- source-able script that sets up the environment
    bin/tipple      -- tipple itself
    bin/tclsh       -- wrapper for system tclsh that sources activate first

Also:

    tipple.txt  -- configuration
    src/        -- where source repos/archives get downloaded and unpacked.  Do Not put this in starpacks.


................................................................................
    cp -a modules/* $TCL8_6_TM_PATH
    cp -a bin/*     DIR/bin/

It must *not*:

 * rely at runtime on anything not in these directories
 * require path-dependent preprocessing



*(means to install packages according to metadata in the form of `tipple.txt` or other "blessed" formats will come soon)*


## Metadata

It's useful for tipple to:

 * track what packages it has already installed in a repo
 * recursively install requirements of a given package

This is done with a simple text format `tipple.txt`, which is found in:

 * the root of the tipple environment (DIR)
 * the root of a "well-behaved" package


tipple maintains `DIR/tipple.txt` by appending to it, and will look for `tipple.txt` in any packages it's asked to install.

The format is as simple as can be:

    # this is a comment, as you might expect
    
    # empty lines are allowed, and ignored
    
    # specify teapot repos to use, in order of preference
    teapot https://teapot.rkeene.org/
    teapot https://teapot.activestate.org/
    
    # MAYBE: optionally specify architecture for fetching binary pkgs from teapot
    architecture OS ARCH











    
    # require from teapot, latest version
    require package-name
    
    # require from teapot, specific version
    require package-name version
    
................................................................................
    require git+https://github.com/somebody/somepackage
    require git+https://github.com/somebody/somepackage branch-or-tag-or-commit-id
    
    # require from fossil, latest trunk or specific checkout
    require fossil+https://chiselapp.com/user/somebody/repository/somepackage
    require fossil+https://chiselapp.com/user/somebody/repository/somepackage branch-or-tag-or-commit-id












## Use cases (mostly articulated by stevel)

 * I want to install my own copies of packages that are not installed on the system, and I may not have root
 * I want to install a more up-to-date copy of a package that is already installed on the system
 * I want to wrap a script (as a starpack or just an archive) and include a copy of the dependent packages
 * I want to run a script to download and install all the dependencies of a package or script that I have
................................................................................
 * <https://github.com/AngryLawyer/mug/>
 * python's `pip` + `virtualenv`

Related, but beyond the scope of this project:

 * <https://chiselapp.com/user/aspect/repository/sdx/wiki?name=howto>
 * `../hacks/cuppa` has some stuff for processing teapot + gutter metadata


Bigger, more capable but much hairier things:

 * <https://github.com/ActiveState/teapot>
 * <https://core.tcl.tk/akupries/kettle/index>
 * <http://fossil.etoyoc.com/fossil/odie/home>







<

>







 







|
|
|
|
|
|







 







>
>




|

|

|
|
|
|
|
|
|
>
|
<
<
<
<
<
<
<
<
|





>
>
>
>
>
>
>
>
>
>
>







 







>
>
>
>
>
>
>
>
>
>







 







>






9
10
11
12
13
14
15

16
17
18
19
20
21
22
23
24
..
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
..
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
...
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
...
175
176
177
178
179
180
181
182
183
184
185
186
187
188
  * no reliance on any packages not shipped with the core.  `sqlite3` only possible exception
 * access packages from git/fossil repos and teapot
 * use a simple requirements txt format
 * easily consume sensibly-structured source repos without further work on the author's part

Requirements:


 * Tcl 8.6+
 * a unix-like environment (this limitation may be revisited in future)
 * any of `curl`, `wget`, `fetch`
 * for installing from repos, `git`, `fossil`

Non-goals:

 * building extensions from source.  Those can come from a teapot
 * doing more than the 80% necessary to bootstrap newbies
................................................................................
 * a fossil or git repository


## Filesystem

Tipple creates a project directory consisting of:

    bin/                -- executables
    lib/tclX.Y          -- pkgIndex.tcl style packages
    lib/tclX/site-tcl/  -- .tm style modules
    bin/activate        -- source-able script that sets up the environment
    bin/tipple          -- tipple itself
    bin/tclsh           -- wrapper for system tclsh that sources activate first

Also:

    tipple.txt  -- configuration
    src/        -- where source repos/archives get downloaded and unpacked.  Do Not put this in starpacks.


................................................................................
    cp -a modules/* $TCL8_6_TM_PATH
    cp -a bin/*     DIR/bin/

It must *not*:

 * rely at runtime on anything not in these directories
 * require path-dependent preprocessing

The source directory will be left around (in `DIR/src`) so users can view documentation and examples in there.

*(means to install packages according to metadata in the form of `tipple.txt` or other "blessed" formats will come soon)*


## Environment Metadata:  `tclenv.txt`

At the root of the environment, `tclenv.txt` records some metadata about the environment.  It looks like:

    # this is a comment, as you might expect
    # empty lines are ignored
    
    tcl_version 8.6
    
    # directories where things are installed to:
    lib_dir     lib/tcl8.6
    tm_dir      lib/tcl8/site-tcl
    








    # teapot repos to use, in order of preference
    teapot https://teapot.rkeene.org/
    teapot https://teapot.activestate.org/
    
    # MAYBE: optionally specify architecture for fetching binary pkgs from teapot
    architecture OS ARCH


## Package Metadata: `tipple.txt`

Tipple looks in the root of any package it installs for `tipple.txt`, which can specify requirements that will be satisfied recursively.  It looks like:

    # this is a comment, as you might expect
    # empty lines are allowed, and ignored
    
    # strictly optional.
    require Tcl 8.6
    
    # require from teapot, latest version
    require package-name
    
    # require from teapot, specific version
    require package-name version
    
................................................................................
    require git+https://github.com/somebody/somepackage
    require git+https://github.com/somebody/somepackage branch-or-tag-or-commit-id
    
    # require from fossil, latest trunk or specific checkout
    require fossil+https://chiselapp.com/user/somebody/repository/somepackage
    require fossil+https://chiselapp.com/user/somebody/repository/somepackage branch-or-tag-or-commit-id


### Coming soon

A `tipple.txt` file might also want to be written for an upstream repo that we don't control.  This **will** be supported by creating a local `tipple.txt` that can use additional directives:

    provide somepackage 0.1.2
    source https://some.url/tarball.tar.gz
    require some-dependency
    patch some-file.patch


## Use cases (mostly articulated by stevel)

 * I want to install my own copies of packages that are not installed on the system, and I may not have root
 * I want to install a more up-to-date copy of a package that is already installed on the system
 * I want to wrap a script (as a starpack or just an archive) and include a copy of the dependent packages
 * I want to run a script to download and install all the dependencies of a package or script that I have
................................................................................
 * <https://github.com/AngryLawyer/mug/>
 * python's `pip` + `virtualenv`

Related, but beyond the scope of this project:

 * <https://chiselapp.com/user/aspect/repository/sdx/wiki?name=howto>
 * `../hacks/cuppa` has some stuff for processing teapot + gutter metadata
 * <https://sourceforge.net/projects/kbskit/> inspired some of the `tipple.txt` commands

Bigger, more capable but much hairier things:

 * <https://github.com/ActiveState/teapot>
 * <https://core.tcl.tk/akupries/kettle/index>
 * <http://fossil.etoyoc.com/fossil/odie/home>

Changes to tipple/tipple.tcl.

44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
..
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
        } else {
            puts "Setting up new directory: $topdir"
        }

        set tclver [info tclversion]
        regexp {^(\d+).(\d+)} $tclver -> majver minver

        set bindir $topdir/bin
        set libdir $topdir/lib/tcl$tclver
        set moddir $topdir/lib/tcl${majver}/site-tcl

        puts "mkdir -p $topdir $bindir $libdir $moddir"
        file mkdir $topdir $bindir $libdir $moddir

        createfile $bindir/activate [subst -noc {
            # source this file to initialize your env:
            PATH="$bindir:\$PATH"
................................................................................
                #!/bin/sh
                . "$bindir/activate"
                exec "$tclexe" "\$@"
            }] -permissions 0755

        }

        createfile $topdir/tipple.txt [subst {
            # Tcl environment initialised at [clock format [clock seconds]]
            tcl_version $tclver
            lib_dir [list $libdir]
            tm_dir  [list $moddir]

        }]
    }
}

proc main {args} {
    if {$args eq ""} {set args "help"}







|
|
|







 







|


|
|







44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
..
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
        } else {
            puts "Setting up new directory: $topdir"
        }

        set tclver [info tclversion]
        regexp {^(\d+).(\d+)} $tclver -> majver minver

        set bindir $topdir/[set relbindir bin]
        set libdir $topdir/[set rellibdir lib/tcl$tclver]
        set moddir $topdir/[set relmoddir lib/tcl${majver}/site-tcl]

        puts "mkdir -p $topdir $bindir $libdir $moddir"
        file mkdir $topdir $bindir $libdir $moddir

        createfile $bindir/activate [subst -noc {
            # source this file to initialize your env:
            PATH="$bindir:\$PATH"
................................................................................
                #!/bin/sh
                . "$bindir/activate"
                exec "$tclexe" "\$@"
            }] -permissions 0755

        }

        createfile $topdir/tclenv.txt [subst {
            # Tcl environment initialised at [clock format [clock seconds]]
            tcl_version $tclver
            lib_dir [list $rellibdir]
            tm_dir  [list $relmoddir]

        }]
    }
}

proc main {args} {
    if {$args eq ""} {set args "help"}