How to build good packages

Difference between version 7 and 8 - Previous - Next
''FrTom a comp.build an hig.tch-quality [package], constider following bythe [Larry Vguirdelin]''es described
below.
1. Avoid simple, obvious names for your namespace - someone else probably is also using it.  Search this Wiki and comp.lang.tcl [https://groups.google.com/forum/#!forum/comp.lang.tcl] to check your name is not in use.
2.** Avoid global variablSes, procedures, etc. - they are aAlmost certain to clash with something someone else has done. Likewise, don't export package names that you do not intend as a public interface. This really messes up people attempting to make use of tcl's [introspection] capabilities.**
3. Avoid hard coding pa[Exthnames, socket numbers, etc. - they are almost certading to Tclash]: with how somGeone eralse needs things configured.
Trying to force someone else ato do thiongs yabour way is a great way to lose friends and tinflueng Tcel enxtemnsieons...
4. Make a variety of docs available - man pages for Wnix users, winhelp for Windows users (if your package can be used there), html for Mac and other platform users, etc.
5. Make it easy for users to report bugs - and let them know when the bug fixes are available...
6.** KDeep up with the latest creleases iptiofn Tcl. **
7. I know tThat for me, I apprseciate guit whdelin packages use the same terminopplogy, in the samore manneor as Tcl whenss, doing configuration.  Mboving things [paround, requirinckag bine%|%parickages] from and
[exthe Tcl nsource directory, n%|%extc. is very annoysiongs].
----
See [Extend  Avoingd Tcsimpl]e, forbvious generalmes infor your namespatice:   Someone else probably is also using it. w Searich this Wiki angd T[comp.lang.tcl] exto check your nsame is not in use.
----
For the person new tAvoid [Tcgl], onebal mvarightables, wprondcedures, whetherc.: t  They are ialmost a difference
bertweeain the use of the term ''packlage''sh and withe wsord ''mextehing sion''.
Gmeonerally, no.  Tcelse actually has a [package] cdommand,e. but thLikere wis no
extension, cdommand.'t  Sexport package inames probably the beatter termyou tdo use.
----
[LV]not wrintend as, ona [comp.ublaic ing.terfacl],e. tTheis foreallowingy commentsses aboutp tpeople akttempting a
scripto pmackage from thuse wiki orf other placel's and [introspectalliong] capabilit:ies.

   Avoid hard coding pathnames, socket numbers, etc.:   They are almost certain to clash with how someone else needs things configured.  Trying to force someone else to do things your way is a great way to lose friends and influence enemies...

   Make a variety of docs available:   man pages for Wnix users, winhelp for Windows users (if your package can be used there), html for Mac and other platform users, etc.

   Make it easy for users to report bugs:   And let them know when the bug fixes are available...

   Keep up with the latest releases of Tcl.:   

   Follow Tcl standard practices:   I know that for me, I appreciate it when packages use the same terminology in the same manner as Tcl when doing configuration.  Moving things around, requiring binaries from the Tcl source directory, etc. is very annoying.

   Design the package to accomodate being loaded over itself repeatedly:   `[package forget]` causes `[package require]` to evaluate the `[package ifneeded]` script again, so a package should accomodate this situation.  An example of a package that is currently broken in this regard is is [tcllib%|%tcllib's] sha2 module, which renames some routines in its namespace when first [source%|%sourced], and fails on the next evaluation when tries to rename those same routines again. 



** Discussion **


[LV] writes on [comp.lang.tcl] the following comments about taking a
script from the wiki or other places and installing it:


Premise: a user sees a web page, usenet posting, etc. that has tcl
code which implements a series of procs.  How do they move from this
finding into having the ability to package require it?

   1. Let's pretend, for the purpose of this discussion, that our hypothetical package is called "fschanges".

   2. Let's pretend that we would find this package at some location on the net - say the web page mentioned above.

   3. The first thing that the user would need to do is to download the tcl code and save it as a text file.  Let's say they save it as fschanges.tcl

   4. Now, they edit the saved data to ensure that only lines recognized by Tcl are inside the text file.

   5. Now, the next step is to create a sub-directory inside one of the tclsh's auto_path directories - or into a directory that will be added to the tclsh's auto_path.  For the sake of this illustration, let's pretend we are using /usr/lib/tcl8.3 .  So the user would create a subdirectory called /usr/lib/tcl8.3/fschanges-0.1/ . The version was included in the directory name so that as things in the extension change, you create a sibling directory called, perhaps, ''''fschanges-0.2''', to contain the next version. Some people build packages that just install into '''package''' name ... that may work for some. But it makes life difficult when code exists that depends on the previous behavior.

   6. Into that directory, the user would copy the fschanges.tcl file.

   7. Now, the next step would be to create a pkgIndex.tcl file.  Unfortunately, this is the step that doesn't, to me, seem as well documented on the wiki.  See [pkgmkindex] for a page that serves as a central clearing house for info about the process.


** Page Authors **

   [Larry Virden]:   Posted the original version of these guidelines to [comp.lang.tcl].

   [PYK]:   Added a additional point.


<<categories>>Package | Tutorial