"Fossies" - the Fresh Open Source Software Archive
Member "aspell-0.60.8/README" (12 Oct 2019, 19961 Bytes) of package /linux/misc/aspell-0.60.8.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard
) with prefixed line numbers.
Alternatively you can here view
the uninterpreted source code file.
See also the latest Fossies "Diffs"
side-by-side code changes report for "README": 0.60.7_vs_0.60.8
1 Appendix A Installing
4 Aspell requires gcc 2.95 (or better) as the C++ compiler. Other C++
5 compilers should work with some effort. Other C++ compilers for mostly
6 POSIX compliant (Unix, Linux, BeOS, Cygwin) systems should work without
7 any major problems provided that the compile can handle all of the
8 advanced C++ features Aspell uses. C++ compilers for non-Unix systems
9 might work but it will take some work. Aspell at very least requires a
10 Unix-like environment ('sh', 'grep', 'sed', 'tr', ...), and Perl in
11 order to build. Aspell also uses a few POSIX functions when necessary.
13 The latest version can always be found at GNU Aspell's home page at
16 A.1 Generic Install Instructions
19 ./configure && make
21 For additional 'configure' options type './configure --help'. You
22 can control what C++ compiler is used by setting the environment
23 variable 'CXX' before running configure and you can control what flags
24 are passed to the C++ compile via the environment variable 'CXXFLAGS'.
25 Static libraries are disabled by default since static libraries will not
26 work right due to the mixing of C and C++. When a C program links with
27 the static libraries in Aspell it is likely to crash because Aspell's
28 C++ objects are not getting initialized correctly. However, if for some
29 reason you want them, you can enable them via '--enable-static'.
31 Aspell should then compile without any additional user intervention.
32 If you run into problems please first check the sections below as that
33 might solve your problem.
35 To install the program simply type
37 make install
39 After Aspell is installed at least one dictionary needs to be
40 installed. You can find them at <http://aspell.net/>. The 'aspell'
41 program must be in your path in order for the dictionaries to install
44 If you do not have Ispell or the traditional Unix 'spell' utility
45 installed on your system then you should also copy the compatibility
46 scripts 'ispell' and 'spell' located in the 'scripts/' directory into
47 your binary directory which is usually '/usr/local/bin' so that programs
48 that expect the 'ispell' or 'spell' command will work correctly.
50 A.2 HTML Manuals and 'make clean'
53 The Aspell distribution includes HTML versions of the User and
54 Developer's manual. Unfortunately, doing a 'make clean' will erase
55 them. This is due to a limitation of automake which is not easily
56 fixed. If makeinfo is installed they can easily be rebuild with 'make
57 aspell.html aspell-dev.html', or you can unpack them from the tarball.
59 A.3 Curses Notes
62 If you are having problems compiling 'check_funs.cpp' then the most
63 likely reason is due to incompatibilities with the curses implementation
64 on your system. You should first try disabling the "wide" curses
65 library with the '--disable-wide-curses' configure option. By doing so
66 you will lose support for properly displaying UTF-8 characters but you
67 may still be able to get the full screen interface. If this fails then
68 you can disable curses support altogether with the '--disable-curses'
69 configure option. By doing this you will lose the nice full screen
70 interface but hopefully you will be able to at least get Aspell to
71 compile correctly.
73 If the curses library is installed in a non-standard location then
74 you can specify the library and include directory with
75 '--enable-curses=LIB' and '--enable-curses-include=DIR'.
77 'LIB' can either be the complete path of the library--for example
79 or the name of the library (for example 'ncurses') or a combined
80 location and library in the form '-LLIBDIR -lLIB' (for example
81 '-L/usr/local/ncurses/lib -lncurses').
83 DIR is the location of the curses header files (for example
86 A.3.1 Unicode Support
89 In order for Aspell to correctly spell check UTF-8 documents in full
90 screen mode the "wide" version of the curses library must be installed.
91 This is different from the normal version of curses library, and is
92 normally named 'libcursesw' (with a 'w' at the end) or 'libncursesw'.
93 UTF-8 documents will not display correctly without the right curses
94 version installed.
96 In addition your system must also support the 'mblen' function.
97 Although this function was defined in the ISO C89 standard (ANSI
98 X3.159-1989), not all systems have it.
100 A.4 Loadable Filter Notes
103 Support for being able to load additional filter modules at run-time has
104 only been verified to work on Linux platforms. If you get linker errors
105 when trying to use a filter, then it is likely that loadable filter
106 support is not working yet on your platform. Thus, in order to get
107 Aspell to work correctly you will need to avoid compiling the filters as
108 individual modules by using the '--enable-compile-in-filters'
109 'configure' option.
111 A.5 Using 32-Bit Dictionaries on a 64-Bit System
114 Due to an oversight, Aspell compiled dictionaries not only depend on the
115 endian order, they also depend on the the size of the 'size_t' type,
116 which is generally different on 32 and 64-bit systems. The 'size_t'
117 type is used in the hash function of the compiled dictionaries. To
118 force the hash function to use a 32-bit integer instead, use the
119 '--enable-32-bit-hash-fun' configure option. This option will allow you
120 to use dictionaries compiled on a 32-bit machine on a 64-bit one as long
121 as the endian order is the same. Of course, dictionaries compiled on a
122 64-bit machine without this option enabled will no longer be usable. If
123 Aspell detects that an incompatible hash function is used, it will fail
125 Error: The file "SOME-FILE" is not in the proper format.
126 Incompatible hash function.
128 A.6 Upgrading from Aspell 0.60.7
131 To prevent a potentially unbounded buffer over-read, Aspell no longer
132 supports null-terminated UCS-2 and UCS-4 encoded strings with the
133 original C API. Null-termianted 8-bit or UTF-8 encoded strings are still
134 supported, as are UCS-2 and UCS-4 encoded strings when the length is
135 passed in.
137 As of Aspell 0.60.8 a function from the original API that expects an
138 encoded string as a parameter will return meaningless results (or an
139 error code) if string is null terminated and the encoding is set to
140 'ucs-2' or 'ucs-4'. In addition, a single:
141 ERROR: aspell_speller_check: Null-terminated wide-character strings unsupported when used this way.
142 will be printed to standard error the first time one of those
143 functions is called.
145 Application that use null-terminated UCS-2/4 strings should either
146 (1) use the interface intended for working with wide-characters (*note
147 Through the C API::); or (2) define 'ASPELL_ENCODE_SETTING_SECURE'
148 before including 'aspell.h'. In the latter case is is important that
149 the application explicitly sets the encoding to a known value. Defining
150 'ASPELL_ENCODE_SETTING_SECURE' and not setting the encoding explicitly
151 or allowing user of the application to set the encoding could result in
152 an unbounded buffer over-read.
154 If it is necessary to preserve binary compatibility with older
155 versions of Aspell, the easiest thing would be to determine the length
156 of the UCS-2/4 string--in bytes--and pass that in. Due to an
157 implemenation detail, existing API functions can be made to work with
158 null-terminated UCS-2/4 strings safely by passing in either '-2' or '-4'
159 (corresponding to the width of the character type) as the size. Doing
160 so, however, will cause a buffer over-read for unpatched version of
161 Aspell. To avoid this it will be necessary to parse the version string
162 to determine the correct value to use. However, no official support
163 will be provided for the latter method.
165 If the application can not be recompiled, then Aspell can be
166 configured to preserve the old behavior by passing
167 '--enable-sloppy-null-term-strings' to 'configure'. When Aspell is
168 compiled this way the version string will include the string ' SLOPPY'.
170 A.7 Upgrading from Aspell 0.50
173 The dictionary format has changed so dictionaries will need to be
176 All data, by default, is now included in 'LIBDIR/aspell-0.60' so that
177 multiple versions of Aspell can more peacefully coexist. This included
178 both the dictionaries and the language data files which were stored in
179 'SHAREDIR/aspell' before Aspell 0.60.
181 The format of the character data files has changed. The new
182 character data files are installed with Aspell so you should not have to
183 worry about it unless you made a custom one.
185 The dictionary option 'strip-accents' has been removed. For this
186 reason the old English dictionary (up to 0.51) will no longer work. A
187 new English dictionary is now available which avoids using this option.
188 In addition the 'ignore-accents' option is currently unimplemented.
190 The flag '-l' is now a shortcut for '--lang', instead of '--list' as
191 it was with Aspell 0.50.
193 A.7.1 Binary Compatibility
196 The Aspell 0.60 library is binary compatible with the Aspell 0.50
197 library. For this reason I chose _not_ to increment the major version
198 number (so-name) of the shared library by default which means programs
199 that were compiled for Aspell 0.50 will also work for Aspell 0.60.
200 However, this means that having both Aspell 0.50 and Aspell 0.60
201 installed at the same time can be pragmatic. If you wish to allow both
202 Aspell 0.50 and 0.60 to be installed at the same time then you can use
203 the configure option '--incremented-soname' which will increment
204 so-name. You should only use this option if you know what you are
205 doing. It is up to you to somehow ensure that both the Aspell 0.50 and
206 0.60 executables can coexist.
208 If after incrementing the so-name you wish to allow programs compiled
209 for Aspell 0.50 to use Aspell 0.60 instead (thus implying that Aspell
210 0.50 is not installed) then you can use a special compatibility library
211 which can be found in the 'lib5' directory. This directory will not be
212 entered when building or installing Aspell so you must manually build
213 and install this library. You should build it after the rest of Aspell
214 is built. The order in which this library is installed, with relation
215 to the rest of Aspell, is also important. If it is installed _after_
216 the rest of Aspell then new programs will link to the old library (which
217 will work for Aspell 0.50 or 0.60) when built, if installed _before_,
218 new programs will link with the new library (Aspell 0.60 only).
220 A.8 Upgrading from Aspell .33/Pspell .12
223 Aspell has undergone an extremely large number of changes since the
224 previous Aspell/Pspell release. For one thing Pspell has been merged
225 with Aspell so there in no longer two separate libraries you have to
226 worry about.
228 Because of the massive changes between Aspell/Pspell and Aspell 0.50
229 you may want to clean out the old files before installing the the new
230 Aspell. To do so do a 'make uninstall' in the original Aspell and
231 Pspell source directories.
233 The way dictionaries are handled has also changed. This includes a
234 change in the naming conventions of both language names and
235 dictionaries. Due to the language name change, your old personal
236 dictionaries will not be recognized. However, you can import the old
237 dictionaries by running the 'aspell-import' script. This also means
238 that dictionaries designed to work with older versions of Aspell are not
239 likely to function correctly. Fortunately new dictionary packages are
240 available for most languages. You can find them off of the Aspell home
241 page at <http://aspell.net>.
243 The Pspell ABI is now part of Aspell except that the name of
244 everything has changed due to the renaming of Pspell to Aspell. In
245 particular please note the following name changes:
247 pspell -> aspell
248 manager -> speller
249 emulation -> enumeration
250 master_word_list -> main_word_list
252 Please also note that the name of the 'language-tag' option has
253 changed to 'lang'. However, for backward compatibility the
254 'language-tag' option will still work.
256 However, you should also be able to build applications that require
257 Pspell with the new Aspell as a backward compatibility header file is
260 Due to a change in the way dictionaries are handled, scanning for
261 '.pwli' files in order to find out which dictionaries are available will
262 no longer work. This means that programs that relied on this technique
263 may have problems finding dictionaries. Fortunately, GNU Aspell now
264 provided a uniform way to list all installed dictionaries via the c API.
265 See the file 'list-dicts.c' in the 'examples/' directory for an example
266 of how to do this. Unfortunately there isn't any simple way to find out
267 which dictionaries are installed which will work with both the old
268 Aspell/Pspell and the new GNU Aspell.
270 A.9 Upgrading from a Pre-0.50 snapshot
273 At the last minute I decided to merge the 'speller-util' program into
274 the main 'aspell' program. You may wish to remove that 'speller-util'
275 program to avoid confusion. This also means that dictionaries designed
276 to work with the snapshot will no longer work with the official release.
278 A.10 WIN32 Notes
281 A.10.1 Getting the WIN32 version
284 The native Aspell/WIN32 port is no longer being maintained. The best
285 way to get Aspell for Windows is to use the MSYS2 binaries. MSYS2 is
286 available at <https://www.msys2.org/>.
288 Binaries for Aspell 0.50 are still available at
289 <http://aspell.net/win32/> but they are no longer supported. If you are
290 interested in updating them for Aspell 0.60 please let me know.
292 A.10.2 Building the WIN32 version
295 There are two basically different ways of building Aspell using GCC for
296 WIN32: You can either use the Cygwin compiler, which will produce
297 binaries that depend on the POSIX layer in 'cygwin1.dll'. The other way
298 is using MinGW GCC, those binaries use the native C runtime from
299 Microsoft (MSVCRT.DLL).
301 A.10.2.1 Building Aspell using Cygwin
304 This works exactly like on other POSIX compatible systems using the
305 './configure && make && make install' cycle. Some versions of Cygwin
306 GCC will fail to link, this is caused by an incorrect 'libstdc++.la' in
307 the '/lib' directory. After removing or renaming this file, the build
308 progress should work (GCC-2.95 and GCC-3.x should work).
310 A.10.2.2 Building Aspell using MinGW
313 There are several different ways to build Aspell using MinGW. The
314 easiest way is to use a Cygwin compiler but instruct it to build a
315 native binary rather than a Cygwin one. To do this configure with:
317 ./configure CFLAGS='-O2 -mno-cygwin' CXXFLAGS='-O2 -mno-cygwin'
319 You may also want to add the option '--enable-win32-relocatable' to
320 use more windows friendly directories. *Note Win32-Directories::. In
321 this case configure with:
323 ./configure CFLAGS='-O2 -mno-cygwin' CXXFLAGS='-O2 -mno-cygwin' --enable-win32-relocatable
325 It should also be possible to build Aspell using the MSYS
326 environment. But this has not been very well tested. If building with
327 MSYS _do not_ add 'CFLAGS ...' to configure.
329 A.10.2.3 Building Aspell without using Cygwin or MSYS
332 It is also possible to build Aspell without Cygwin of MinGW by using the
333 files in the 'win32/' subdirectory. However, these files have not been
334 updated to work with Aspell 0.60. Thus the following instructions will
335 not work without some effort. If you do get Aspell to compile this way
336 please send me the updated files so that I can include them with the
337 next release.
339 To compile Aspell with the MinGW compiler, you will need at least
340 GCC-3.2 (as shipped with MinGW-2.0.3) and some GNU tools like 'rm' and
341 'cp'. The origin of those tools doesn't matter, it has shown to work
342 with any tools from MinGW/MSys, Cygwin or Linux. To build Aspell, move
343 into the 'win32' subdirectory and type 'make'. You can enable some
344 additional build options by either commenting out the definitions at the
345 head of the Makefile or passing those values as environment variables or
346 at the 'make' command line. Following options are supported:
349 If set to "1", the binaries will include debugging information
350 (resulting in a much bigger size).
353 Enter the path to the pdcurses library here, in order to get a
354 nicer console interface (see below).
357 Enter the filename of MS 'lib.exe' here, if you want to build
358 libraries that can be imported from MS Visual C++.
361 If set to "1", Aspell will detect the prefix from the path where
362 the DLL resides (see below for further details).
365 Sets a prefix to be used for cross compilation (e.g.
366 '/usr/local/bin/i586-mingw32msvc-' to cross compile from Linux).
368 There are also a MinGW compilers available for Cygwin and Linux, both
369 versions are able to compile Aspell using the prebuilt 'Makefile'.
370 While the Cygwin port automatically detects the correct compiler, the
371 Linux version depends on setting the 'TARGET' variable in the 'Makefile'
372 (or environment) to the correct compiler prefix.
374 Other compilers may work. There is a patch for MS Visual C++ 6.0
375 available at <ftp://ftp.gnu.org/gnu/aspell>, but it needs a lot of
376 changes to the Aspell sources. It has also been reported that the Intel
377 C++ compiler can be used for compilation.
379 A.10.3 (PD)Curses
382 In order to get the nice full screen interface when spell checking
383 files, a curses implementation that does not require Cygwin is required.
384 The PDCurses (<http://pdcurses.sourceforge.net>) implementation is known
385 to work, other implementations may work however they have not been
386 tested. See the previous section for information on specifying the
387 location of the curses library and include file.
389 Curses notes:
391 * PDcurses built with MinGW needs to be compiled with
392 '-DPDC_STATIC_BUILD' to avoid duplicate declaration of 'DllMain'
393 when compiling 'aspell.exe'.
395 * The curses enabled version can cause trouble in some shells (MSys
396 'rxvt', 'emacs') and will produce errors like 'initscr() LINES=1
397 COLS=1: too small'. Use a non-curses version for those purposes.
399 A.10.4 Directories
402 If Aspell is configured with '--enable-win32-relocatable' or compiled
403 with 'WIN32_RELOCATABLE=1' when using a Makefile, it can be run from any
404 directory: it will set 'PREFIX' according to its install location
405 (assuming it resides in 'PREFIX\\bin'). Your personal wordlists will be
406 saved in the 'PREFIX' directory with their names changed from
407 '.aspell.LANG.*' to 'LANG.*' (you can override the path by setting the
408 'HOME' environment variable).
410 A.10.5 Installer
413 The installer registers the DLLs as shared libraries, you should
414 increase the reference counter to avoid the libraries being uninstalled
415 if your application still depends on them (and decrease it again when
416 uninstalling your program). The reference counters are located under:
419 The install location and version numbers are stored under
423 A.10.6 WIN32 consoles
426 The console uses a different encoding than GUI applications, changing
427 this to to a Windows encoding (e.g. 1252) is not supported on Win9x/Me.
428 On WinNT (and later) those codepages can be set by first changing the
429 console font to 'lucida console', then changing the codepage using 'chcp
432 Some alternative shells (e.g. MSys' 'rxvt' or Cygwin's 'bash') do a
433 codepage conversion (if correctly set up), so running Aspell inside
434 those shells might be a workaround for Win9x.