Update PUI to use ffi-curl
[sxemacs] / contrib / README
1 -*- text -*-
2
3 In here you'll find a few odds and sods that may or may not be
4 useful.
5
6 File List:
7 =========
8         do_builds.sh..................automate builds
9         git-post-receive-hook.sample..git hook to send email automatically for merge requests
10         git-for-steve.sh..............setup a for-steve branch to send patches to the master branch
11         make-pkg.sh...................bash script to create a SXEmacs tar package 
12         pop3.el.patch.................SXEmacs native OpenSSL goodies 
13         report-build-failure.sh.......bash script to send a build report failure 
14         show-tty-256-colors.pl........Perl script to test 256 color output on terminal
15         smtpmail.el.patch.............SXEmacs native OpenSSL goodies
16         starttls.el.patch.............SXEmacs native OpenSSL goodies
17         tar-build-failure.sh..........bash script w/ tar of build report failure
18         tty-colors.c..................C program to check the terminal color definitions
19
20
21 More Info:
22 =========
23
24 do_builds.sh:
25 ------------
26
27 This script allows the automation of the builds with several different
28 configure options.
29 It does autogen.sh, configure and reports success and of failure.
30 To setup:
31
32    1. Create a directory *outside* of the source directory in order
33    not to be "hammered" by autogen. You use a build directory directly
34    below the top source directory IF you do not set the HAMMER variable
35    in the configuration file (,,conf)
36
37    2. Run the script from *that* directory. That will create a ,,conf 
38    file, which you *must* edit to at least point to the sxemacs source
39    directory.
40
41    3. Create several .conf files, one for each of you different
42    configurations. On this file place all the options you'd usually
43    pass on to configure. If you would set environment variables like
44    CC or CFLAGS, you can do so at the end of the file with <var>=<value>
45    
46    4. Execute do_builds.sh
47
48 Nelson Ferreira <njsf@sxemacs.org>
49
50
51 git-post-receive-hook.sample
52 ----------------------------
53 This hook is meant as git hook (ie to be placed in the hooks directory
54 of your publicly accessible repository) as a way to automatically send
55 emails when you want something to be merged to the master branch.
56
57 It assumes you will use a for-steve branch, as git-to-steve.sh will do
58 for you, so it will only send emails for changes to that branch.
59
60 This script will not send an email on a "fast-forward" or "merge"
61 commit, so that you won't bother Steve if you keep a long lived
62 for-steve branch, and even share it accross machines...
63
64 To use, just place it under the name post-receive in the hooks
65 directory of your git public repository.
66
67 You may wish to review it and make sure the branch(es) you want to
68 send mail for are there and the location of the post-receive-email
69 script which should come with your git install.
70
71 Nelson Ferreira <njsf@sxemacs.org>
72
73
74 git-for-steve.sh
75 ---------------
76
77 This script will check your git configuration, give you some
78 recommendations of changes and create a for-steve branch so that you
79 use the same convention as the other SXEmacs developers to contribute
80 to the SXEmacs project.
81
82 Nelson Ferreira <njsf@sxemacs.org>
83
84
85 make-pkg.sh:
86 -------------
87 This script conveniently creates a tar from your workspace for use
88 in systems without proper autoconf or tla.
89
90 It needs to be run from the top of source directory and requires
91 the name of the package to be given.
92
93 Usage: contrib/make-pkg.sh <package-name> [<package-location>]
94
95 Example: contrib/make-pkg.sh sxemacs-22.1.9 $HOME/public_html
96 will create a sxemacs-22.1.9.tar.gz in your html area.
97
98 Nelson Ferreira <njsf@sxemacs.org>
99
100
101 pop3.el.patch:
102 -------------
103 This patch is meant to be applied to pop3.el from the mail-lib package.
104
105 This patch provides SSL/TLS support for Gnus based on SXEmacs' native
106 OpenSSL interface.  It works with the stream types 'ssl and 'starttls,
107 so mail-sources already using one of these stream types will just keep
108 on working.
109
110 An example mail source for a POP3 TLS connection:
111
112         (pop :server "some.pop3.server.tld"
113              :user "me"
114              :password "verysecret"
115              :stream starttls)
116
117 An example mail source for a POP3s server:
118
119         (pop :server "some.pop3s.server.tld"
120              :user "anotherme"
121              :password "verysecret"
122              :port 995
123              :stream 'ssl)
124
125 The provided functionality has drop-in behaviour, so anything that worked
126 before will keep on working.
127
128 Sebastian Freundt <hroptatyr@sxemacs.org>
129
130
131 report-build-failure.sh:
132 -----------------------
133 Send an email to the SXEmacs developers mailing list with the details
134 needed to troubleshoot failures to build SXEmacs.
135
136 The script requires your email address.
137
138 Usage: contrib/report-build-failure.sh superhacker@sxemacs.org
139
140 When tla is available the script will find the branch and closeness to
141 the main branch as well as uncommitted changes.
142
143 Nelson Ferreira <njsf@sxemacs.org>
144
145
146 show-tty-256-color.pl:
147 ----------------------
148 This script is from the X distribution and outputs a 6x6x6 color cube
149 as well as a grayscale ramp consistent with the default 256 color xterm
150 settings.
151 You can use it to see if your terminal is capable of showing 256 colors.
152
153 Todd Larason <jtl@molehill.org>
154
155
156 smtpmail.el.patch:
157 -----------------
158 This patch is meant to be applied to smtpmail.el from the mail-lib
159 package.
160
161 This patch provides SSL/TLS support for smtp connections using SXEmacs'
162 native OpenSSL interface.  It works out of the box with the usual
163 credential definitions.
164
165 Additionally extends the smtpmail-starttls-credentials specifications by
166 another argument, the fifth one, which can be a certificate authority's
167 certificate file.  If specified the server must present a valid
168 certificate signed by or verifiably by the certificate authority.
169
170 An example credential:
171
172         (setq smtpmail-starttls-credentials
173               '(("some.smtp.server.tld" 25      ;; server+port
174                  "~/.certs/my.smtpd.key"        ;; the cert's secret key
175                  "~/.certs/my.smtpd.cert"       ;; the public cert
176                  "~/.certs/smtp.server.ca"      ;; server's ca cert
177                 )))
178
179 Sebastian Freundt <hroptatyr@sxemacs.org>
180
181 starttls.el.patch:
182 -----------------
183 This patch is meant to be applied to starttls.el from the mail-lib
184 package.
185
186 This patch provides some basic SSL/TLS functionality used by other stuff
187 in the mail-lib package.  Basically it just pretends to be Josefsson's
188 starttls.el.  Instead of calling the gnutls binary externally the
189 internal OpenSSL API functions are used.
190
191 Sebastian Freundt <hroptatyr@sxemacs.org>
192
193 tar-build-failure.sh
194 --------------------
195 Script that creates a tar file withe the contents that would also
196 be emailed by report-build-failure.sh
197
198 Nelson Ferreira <njsf@sxemacs.org>
199
200
201 tty-colors.c
202 ------------
203 C program using the curses library that detects the number of colors,
204 the code sequences and can show the available colormap.
205 Compile with:
206         gcc -o tty-colors tty-colors.c -lncurses 
207 Invoke with:
208        -m       Do a colormap
209        -c       Do all foreground/background color combinations
210        -f       Force the output of the basic ansi colors
211        -s       Force the use of standout code
212        -bs      Force the use of both bold and standout codes
213        -q       Try to query the color map from the terminal
214
215 Nelson Ferreira <njsf@sxemacs.org>