releasing version 3.20091023

[git.ikiwiki.info.git] / doc / tips / optimising_ikiwiki.mdwn

diff --git a/doc/tips/optimising_ikiwiki.mdwn b/doc/tips/optimising_ikiwiki.mdwn
index fcf3077f85a98bfb2ed649c391610e12eea49b22..cf166998bb8060498222768084d2d774e038e173 100644 (file)
--- a/doc/tips/optimising_ikiwiki.mdwn
+++ b/doc/tips/optimising_ikiwiki.mdwn
@@ -1,8 +1,18 @@
-Is ikiwiki taking too long to build your wiki? Read on for some common
-problems that can be avoided to make ikiwiki run quick.
+Ikiwiki is a wiki compiler, which means that, unlike a traditional wiki,
+all the work needed to display your wiki is done up front. Where you can
+see it and get annoyed at it. In some ways, this is better than a wiki
+where a page view means running a program to generate the page on the fly.
+
+But enough excuses. If ikiwiki is taking too long to build your wiki,
+let's fix that. Read on for some common problems that can be avoided to
+make ikiwiki run quick.

 
 [[!toc]]
 
 
 [[!toc]]
 

+(And if none of that helps, file a [[bug|bugs]]. One other great thing about
+ikiwiki being a wiki compiler is that it's easy to provide a test case when
+it's slow, and get the problem fixed!)
+

 ## rebuild vs refresh
 
 Are you building your wiki by running a command like this?
 ## rebuild vs refresh
 
 Are you building your wiki by running a command like this?


@@ -22,13 +32,13 @@ configured the hook in the usual way.) Most people who have run into this
 problem got in the habit of running `ikiwiki -setup my.setup` by hand
 when their wiki was small, and found it got slower as they added pages.
 
 problem got in the habit of running `ikiwiki -setup my.setup` by hand
 when their wiki was small, and found it got slower as they added pages.
 

-### use the latest version
+## use the latest version

 
 

-If your version of ikiwiki is not [[!verison]], try upgrading. New
+If your version of ikiwiki is not [[!version]], try upgrading. New

 optimisations are frequently added to ikiwiki, some of them yielding
 *enormous* speed increases.
 
 optimisations are frequently added to ikiwiki, some of them yielding
 *enormous* speed increases.
 

-### expensive inlines
+## expensive inlines

 
 Do you have an archive page for your blog that shows all posts, 
 using an inline that looks like this?
 
 Do you have an archive page for your blog that shows all posts, 
 using an inline that looks like this?


@@ -123,13 +133,28 @@ This site's own [[plugins/linkmap]] rarely slows it down, because it
 only shows the [[index]] page, and the small set of pages that link to it.
 That is accomplished as follows:
 
 only shows the [[index]] page, and the small set of pages that link to it.
 That is accomplished as follows:
 

-       \[!linkmap pages="index or (backlink(index)"]]
+       \[[!linkmap pages="index or (backlink(index)"]]

 
 ## overhead of the search plugin
 
 Be aware that the [[plugins/search]] plugin has to update the search index
 whenever any page is changed. This can slow things down somewhat.
 
 
 ## overhead of the search plugin
 
 Be aware that the [[plugins/search]] plugin has to update the search index
 whenever any page is changed. This can slow things down somewhat.
 

+## profiling
+
+If you have a repeatable change that ikiwiki takes a long time to build,
+and none of the above help, the next thing to consider is profiling
+ikiwiki. 
+
+The best way to do it is:
+
+* Install [[!cpan Devel::NYTProf]]
+* `PERL5OPT=-d:NYTProf`
+* `export PER5OPT`
+* Now run ikiwiki as usual, and it will generate a `nytprof.out` file.
+* Run `nytprofhtml` to generate html files.
+* Those can be examined to see what parts of ikiwiki are being slow.
+

 ## scaling to large numbers of pages
 
 Finally, let's think about how huge number of pages can affect ikiwiki.
 ## scaling to large numbers of pages
 
 Finally, let's think about how huge number of pages can affect ikiwiki.