+++ /dev/null
-%************************************************************************
-%* *
-<sect>Advice on: sooner, faster, smaller, stingier
-<label id="sooner-faster-quicker">
-<p>
-%* *
-%************************************************************************
-
-Please advise us of other ``helpful hints'' that should go here!
-
-%************************************************************************
-%* *
-<sect1>Sooner: producing a program more quickly
-<label id="sooner">
-<p>
-<nidx>compiling faster</nidx>
-<nidx>faster compiling</nidx>
-%* *
-%************************************************************************
-
-<descrip>
-%----------------------------------------------------------------
-<tag>Don't use @-O@ or (especially) @-O2@:</tag>
-By using them, you are telling GHC that you are willing to suffer
-longer compilation times for better-quality code.
-
-GHC is surprisingly zippy for normal compilations without @-O@!
-
-%----------------------------------------------------------------
-<tag>Use more memory:</tag>
-Within reason, more memory for heap space means less garbage
-collection for GHC, which means less compilation time. If you use
-the @-Rgc-stats@ option, you'll get a garbage-collector report.
-(Again, you can use the cheap-and-nasty @-optCrts-Sstderr@ option to
-send the GC stats straight to standard error.)
-
-If it says you're using more than 20\% of total time in garbage
-collecting, then more memory would help.
-
-If the heap size is approaching the maximum (64M by default), and you
-have lots of memory, try increasing the maximum with the
-@-M<size>@<nidx>-M<size> option</nidx> option, e.g.: @ghc -c -O
--M16m Foo.hs@.
-
-Increasing the default allocation area size used by the compiler's RTS
-might also help: use the @-A<size>@<nidx>-A<size> option</nidx>
-option.
-
-If GHC persists in being a bad memory citizen, please report it as a
-bug.
-
-%----------------------------------------------------------------
-<tag>Don't use too much memory!</tag>
-As soon as GHC plus its ``fellow citizens'' (other processes on your
-machine) start using more than the <em>real memory</em> on your
-machine, and the machine starts ``thrashing,'' <em>the party is
-over</em>. Compile times will be worse than terrible! Use something
-like the csh-builtin @time@ command to get a report on how many page
-faults you're getting.
-
-If you don't know what virtual memory, thrashing, and page faults are,
-or you don't know the memory configuration of your machine,
-<em>don't</em> try to be clever about memory use: you'll just make
-your life a misery (and for other people, too, probably).
-
-%----------------------------------------------------------------
-<tag>Try to use local disks when linking:</tag>
-Because Haskell objects and libraries tend to be large, it can take
-many real seconds to slurp the bits to/from a remote filesystem.
-
-It would be quite sensible to <em>compile</em> on a fast machine using
-remotely-mounted disks; then <em>link</em> on a slow machine that had
-your disks directly mounted.
-
-%----------------------------------------------------------------
-<tag>Don't derive/use @Read@ unnecessarily:</tag>
-It's ugly and slow.
-
-%----------------------------------------------------------------
-<tag>GHC compiles some program constructs slowly:</tag>
-Deeply-nested list comprehensions seem to be one such; in the past,
-very large constant tables were bad, too.
-
-We'd rather you reported such behaviour as a bug, so that we can try
-to correct it.
-
-The parts of the compiler that seem most prone to wandering off for a
-long time are the abstract interpreters (strictness and update
-analysers). You can turn these off individually with
-@-fno-strictness@<nidx>-fno-strictness anti-option</nidx> and
-@-fno-update-analysis@.<nidx>-fno-update-analysis anti-option</nidx>
-
-To figure out which part of the compiler is badly behaved, the
-@-dshow-passes@<nidx>-dshow-passes option</nidx> option is your
-friend.
-
-If your module has big wads of constant data, GHC may produce a huge
-basic block that will cause the native-code generator's register
-allocator to founder. Bring on @-fvia-C@<nidx>-fvia-C option</nidx>
-(not that GCC will be that quick about it, either).
-
-%----------------------------------------------------------------
-<tag>Avoid the consistency-check on linking:</tag>
-
-Use @-no-link-chk@<nidx>-no-link-chk</nidx>; saves effort. This is
-probably safe in a I-only-compile-things-one-way setup.
-
-%----------------------------------------------------------------
-<tag>Explicit @import@ declarations:</tag>
-
-Instead of saying @import Foo@, say @import Foo (...stuff I want...)@.
-
-Truthfully, the reduction on compilation time will be very small.
-However, judicious use of @import@ declarations can make a
-program easier to understand, so it may be a good idea anyway.
-</descrip>
-
-%************************************************************************
-%* *
-<sect1>Faster: producing a program that runs quicker
-<label id="faster">
-<p>
-<nidx>faster programs, how to produce</nidx>
-%* *
-%************************************************************************
-
-The key tool to use in making your Haskell program run faster are
-GHC's profiling facilities, described separately in Section <ref
-name="Profiling" id="profiling">. There is <em>no substitute</em> for
-finding where your program's time/space is <em>really</em> going, as
-opposed to where you imagine it is going.
-
-Another point to bear in mind: By far the best way to improve a
-program's performance <em>dramatically</em> is to use better
-algorithms. Once profiling has thrown the spotlight on the guilty
-time-consumer(s), it may be better to re-think your program than to
-try all the tweaks listed below.
-
-Another extremely efficient way to make your program snappy is to use
-library code that has been Seriously Tuned By Someone Else. You
-<em>might</em> be able to write a better quicksort than the one in the
-HBC library, but it will take you much longer than typing @import
-QSort@. (Incidentally, it doesn't hurt if the Someone Else is Lennart
-Augustsson.)
-
-Please report any overly-slow GHC-compiled programs. The current
-definition of ``overly-slow'' is ``the HBC-compiled version ran
-faster''...
-
-<descrip>
-%----------------------------------------------------------------
-<tag>Optimise, using @-O@ or @-O2@:</tag> This is the most basic way
-to make your program go faster. Compilation time will be slower,
-especially with @-O2@.
-
-At present, @-O2@ is nearly indistinguishable from @-O@.
-
-%----------------------------------------------------------------
-<tag>Compile via C and crank up GCC:</tag> Even with @-O@, GHC tries to
-use a native-code generator, if available. But the native
-code-generator is designed to be quick, not mind-bogglingly clever.
-Better to let GCC have a go, as it tries much harder on register
-allocation, etc.
-
-So, when we want very fast code, we use: @-O -fvia-C -O2-for-C@.
-
-%----------------------------------------------------------------
-<tag>Overloaded functions are not your friend:</tag>
-Haskell's overloading (using type classes) is elegant, neat, etc.,
-etc., but it is death to performance if left to linger in an inner
-loop. How can you squash it?
-
-<descrip>
-<tag>Give explicit type signatures:</tag>
-Signatures are the basic trick; putting them on exported, top-level
-functions is good software-engineering practice, anyway. (Tip: using
-@-fwarn-missing-signatures@<nidx>-fwarn-missing-signatures
-option</nidx> can help enforce good signature-practice).
-
-The automatic specialisation of overloaded functions (with @-O@)
-should take care of overloaded local and/or unexported functions.
-
-<tag>Use @SPECIALIZE@ pragmas:</tag>
-<nidx>SPECIALIZE pragma</nidx>
-<nidx>overloading, death to</nidx>
-
-Specialize the overloading on key functions in your program. See
-Sections <ref name="SPECIALIZE pragmas" id="specialize-pragma"> and
-<ref name="SPECIALIZE instance pragmas" id="specialize-instance-pragma">
-
-% See also: overlapping instances, in Section <ref name="``HBC-ish''
-% extensions implemented by GHC" id="glasgow-hbc-exts">. They are to
-% @SPECIALIZE instance@ pragmas what @= blah@ hacks are to @SPECIALIZE@
-% (value) pragmas...
-
-%ToDo: there's nothing like this at the moment: --SDM
-
-% <tag>``How do I know what's happening with specialisations?'':</tag>
-
-% The @-fshow-specialisations@<nidx>-fshow-specialisations option</nidx>
-% will show the specialisations that actually take place.
-
-% The @-fshow-import-specs@<nidx>-fshow-import-specs option</nidx> will
-% show the specialisations that GHC <em>wished</em> were available, but
-% were not. You can add the relevant pragmas to your code if you wish.
-
-% You're a bit stuck if the desired specialisation is of a Prelude
-% function. If it's Really Important, you can just snap a copy of the
-% Prelude code, rename it, and then SPECIALIZE that to your heart's
-% content.
-
-<tag>``But how do I know where overloading is creeping in?'':</tag>
-
-A low-tech way: grep (search) your interface files for overloaded
-type signatures; e.g.,:
-<tscreen><verb>
-% egrep '^[a-z].*::.*=>' *.hi
-</verb></tscreen>
-</descrip>
-
-%----------------------------------------------------------------
-<tag>Strict functions are your dear friends:</tag>
-and, among other things, lazy pattern-matching is your enemy.
-
-(If you don't know what a ``strict function'' is, please consult a
-functional-programming textbook. A sentence or two of
-explanation here probably would not do much good.)
-
-Consider these two code fragments:
-<tscreen><verb>
-f (Wibble x y) = ... # strict
-
-f arg = let { (Wibble x y) = arg } in ... # lazy
-</verb></tscreen>
-The former will result in far better code.
-
-A less contrived example shows the use of @cases@ instead
-of @lets@ to get stricter code (a good thing):
-<tscreen><verb>
-f (Wibble x y) # beautiful but slow
- = let
- (a1, b1, c1) = unpackFoo x
- (a2, b2, c2) = unpackFoo y
- in ...
-
-f (Wibble x y) # ugly, and proud of it
- = case (unpackFoo x) of { (a1, b1, c1) ->
- case (unpackFoo y) of { (a2, b2, c2) ->
- ...
- }}
-</verb></tscreen>
-
-%----------------------------------------------------------------
-<tag>GHC loves single-constructor data-types:</tag>
-
-It's all the better if a function is strict in a single-constructor
-type (a type with only one data-constructor; for example, tuples are
-single-constructor types).
-
-%----------------------------------------------------------------
-<tag>Newtypes are better than datatypes:</tag>
-
-If your datatype has a single constructor with a single field, use a
-@newtype@ declaration instead of a @data@ declaration. The @newtype@
-will be optimised away in most cases.
-
-%----------------------------------------------------------------
-<tag>``How do I find out a function's strictness?''</tag>
-
-Don't guess---look it up.
-
-Look for your function in the interface file, then for the third field
-in the pragma; it should say @_S_ <string>@. The @<string>@
-gives the strictness of the function's arguments. @L@ is lazy
-(bad), @S@ and @E@ are strict (good), @P@ is ``primitive'' (good),
-@U(...)@ is strict and
-``unpackable'' (very good), and @A@ is absent (very good).
-
-For an ``unpackable'' @U(...)@ argument, the info inside
-tells the strictness of its components. So, if the argument is a
-pair, and it says @U(AU(LSS))@, that means ``the first component of the
-pair isn't used; the second component is itself unpackable, with three
-components (lazy in the first, strict in the second \& third).''
-
-If the function isn't exported, just compile with the extra flag @-ddump-simpl@;
-next to the signature for any binder, it will print the self-same
-pragmatic information as would be put in an interface file.
-(Besides, Core syntax is fun to look at!)
-
-%----------------------------------------------------------------
-<tag>Force key functions to be @INLINE@d (esp. monads):</tag>
-
-Placing @INLINE@ pragmas on certain functions that are used a lot can
-have a dramatic effect. See Section <ref name="INLINE pragmas"
-id="inline-pragma">.
-
-%----------------------------------------------------------------
-<tag>Explicit @export@ list:</tag>
-If you do not have an explicit export list in a module, GHC must
-assume that everything in that module will be exported. This has
-various pessimising effects. For example, if a bit of code is actually
-<em>unused</em> (perhaps because of unfolding effects), GHC will not be
-able to throw it away, because it is exported and some other module
-may be relying on its existence.
-
-GHC can be quite a bit more aggressive with pieces of code if it knows
-they are not exported.
-
-%----------------------------------------------------------------
-<tag>Look at the Core syntax!</tag>
-(The form in which GHC manipulates your code.) Just run your
-compilation with @-ddump-simpl@ (don't forget the @-O@).
-
-If profiling has pointed the finger at particular functions, look at
-their Core code. @lets@ are bad, @cases@ are good, dictionaries
-(@d.<Class>.<Unique>@) [or anything overloading-ish] are bad,
-nested lambdas are bad, explicit data constructors are good, primitive
-operations (e.g., @eqInt#@) are good, ...
-
-%----------------------------------------------------------------
-<tag>Use unboxed types (a GHC extension):</tag>
-When you are <em>really</em> desperate for speed, and you want to get
-right down to the ``raw bits.'' Please see Section <ref name="Unboxed
-types" id="glasgow-unboxed"> for some information about using unboxed
-types.
-
-%----------------------------------------------------------------
-<tag>Use @_ccall_s@ (a GHC extension) to plug into fast libraries:</tag>
-This may take real work, but... There exist piles of
-massively-tuned library code, and the best thing is not
-to compete with it, but link with it.
-
-Section <ref name="Calling~C directly from Haskell" id="glasgow-ccalls"> says a little about how to use C calls.
-
-%----------------------------------------------------------------
-<tag>Don't use @Float@s:</tag>
-We don't provide specialisations of Prelude functions for @Float@
-(but we do for @Double@). If you end up executing overloaded
-code, you will lose on performance, perhaps badly.
-
-@Floats@ (probably 32-bits) are almost always a bad idea, anyway,
-unless you Really Know What You Are Doing. Use Doubles. There's
-rarely a speed disadvantage---modern machines will use the same
-floating-point unit for both. With @Doubles@, you are much less
-likely to hang yourself with numerical errors.
-
-One time when @Float@ might be a good idea is if you have a
-<em>lot</em> of them, say a giant array of @Float@s. They take up
-half the space in the heap compared to @Doubles@. However, this isn't
-true on a 64-bit machine.
-
-%----------------------------------------------------------------
-<tag>Use a bigger heap!</tag>
-
-If your program's GC stats (@-S@<nidx>-S RTS option</nidx> RTS option)
-indicate that it's doing lots of garbage-collection (say, more than
-20\% of execution time), more memory might help---with the
-@-M<size>@<nidx>-M<size> RTS option</nidx> or
-@-A<size>@<nidx>-A<size> RTS option</nidx> RTS options (see
-Section <ref name="RTS options to control the garbage-collector"
-id="rts-options-gc">).
-</descrip>
-
-%************************************************************************
-%* *
-<sect1>Smaller: producing a program that is smaller
-<label id="smaller">
-<p>
-<nidx>smaller programs, how to produce</nidx>
-%* *
-%************************************************************************
-
-Decrease the ``go-for-it'' threshold for unfolding smallish
-expressions. Give a
-@-funfolding-use-threshold0@<nidx>-funfolding-use-threshold0
-option</nidx> option for the extreme case. (``Only unfoldings with
-zero cost should proceed.'') Warning: except in certain specialiised
-cases (like Happy parsers) this is likely to actually
-<em>increase</em> the size of your program, because unfolding
-generally enables extra simplifying optimisations to be performed.
-
-Avoid @Read@.
-
-Use @strip@ on your executables.
-
-%************************************************************************
-%* *
-<sect1>Stingier: producing a program that gobbles less heap space
-<label id="stingier">
-<p>
-<nidx>memory, using less heap</nidx>
-<nidx>space-leaks, avoiding</nidx>
-<nidx>heap space, using less</nidx>
-%* *
-%************************************************************************
-
-``I think I have a space leak...'' Re-run your program with
-@+RTS -Sstderr@,<nidx>-Sstderr RTS option</nidx> and remove all doubt!
-(You'll see the heap usage get bigger and bigger...) [Hmmm... this
-might be even easier with the @-F2s@<nidx>-F2s RTS option</nidx> RTS
-option; so... @./a.out +RTS -Sstderr -F2s@...]
-
-Once again, the profiling facilities (Section <ref name="Profiling"
-id="profiling">) are the basic tool for demystifying the space
-behaviour of your program.
-
-Strict functions are good for space usage, as they are for time, as
-discussed in the previous section. Strict functions get right down to
-business, rather than filling up the heap with closures (the system's
-notes to itself about how to evaluate something, should it eventually
-be required).
projects / ghc-hetmet.git / blobdiff