[reorganize words about slow link times
thomashartman1@gmail.com**20080905091021] addfile ./templates/happs-slow-linking-bug.st
hunk ./templates/happs-slow-linking-bug.st 1
+<h3>HAppS Slow Link Time Workarounds</h3>
+<p>
+The fact that cabal-installing HAppS takes an hour is
+officially a <a
+href="http://code.google.com/p/happs/issues/detail?id=29">bug</a>. Hopefully
+this situation will be remedied as HAppS matures and, eventually, has
+an official release.  
+<p>
+I found this bug pretty problematic when I was experiencing it and I know I'm not the only one. 
+So, I will share some experiences and observations that will hopefully help others,
+and maybe even help diagnose and eventually squash this bug.
+<p>
+First of all, you don't actually need to compile an executable to run a HAppS server, 
+and when you run from inside ghci the link time bug has no effect. So for a while I 
+was doing this, by loading ghci using ./hackInGhci.sh and then running runInGhci inside Main.hs.
+<p>
+Secondly, at some point this problem went away, and my link time dropped from 5-10 minutes to under 10 seconds.
+<p>
+This is definitely due to a change in my own code base, not HAppS repo code, since I am only 
+running against what I cabal installed and not the volatile HAppS library code in darcs.
+At some point I intend to attempt a more precise diagnosis
+by doing binary cuts on my repo and identifying the changes that seem
+to have the biggest impact. I do have some suspicions. 
+<ul>
+  <li>Problems are related to Template Haskell and/or Data.Deriving</li>
+  <li>Splitting up big modules into smaller modules
+      <br>When I saw link times over 5 minutes I tried to isolate the 
+        "slow" methods in a file called "Slow.hs" so that the linking is only slow when that file changes.
+        Lately I removed the Slow module since it didn't seem necessary anymore.</li>
+  <li>Supplying type signatures helps, and the more concrete the type signature the better.
+  <br>So, (askUsers :: Query TutorialState (M.Map String User) ) rather than (askUsers :: MonadReader State m => m (M.Map String User) )
+  <br>tentative idea: ghc -fwarn-missing-signatures and give maximally precise signatures everywhere.</li>
+</ul>
+
+<p>
+
+The shell command ./runServer.sh, which creates an executable and starts the server, also times the compile & link, and rings a bell when it's done. Helpful if slow link times are creeping back in.
hunk ./templates/run-tutorial-locally.st 8
-<p>The cabal installation may take up to an hour, mainly because the HAppS-Server installation is slow, but it should succeed in one shot. Incidentally, the fact that installing HAppS takes this long is arguably a <a href="http://code.google.com/p/happs/issues/detail?id=29">bug</a>. Hopefully this situation will be remedied as HAppS matures and, eventually, has an official release</p>
+<p>The cabal installation may take up to an hour, mainly because the
+HAppS-Server installation is slow, but it should succeed in one
+shot. This is a symptom of the <a href="/tutorial/happs-slow-linking-bug">HAppS slow linking bug</a>.
hunk ./templates/run-tutorial-locally.st 18
-    <li>Running the app: there are a couple of approaches, depending on what you want to do.
-        <br>Mainly, if you are not a patient kind of person, you don't want to compile and link your app
-	ever time you make a change, because linking in HAppS can be slow.
-        I've seen linking of the tutorial code take up to ten minutes.
-	Oh, and it hogs  memory like crazy, and the cpu gets hot and the fan goes into overdrive.
-        This is almost certainly a symptom of the same
-	<a href="http://code.google.com/p/happs/issues/detail?id=29">HAppS slow linking bug</a> mentioned above.   
-    <ul>
-    <li>The simplest thing is to just run the happs-tutorial binary as mentioned above.
-        Shutdown is simple too: ctrl-c.
+    <li>For running the app, there are actually a couple of approaches.
+       <ul>
+        <li>If you haven't made changes in the code, run the happs-tutorial binary that got cabal-installed.</li>
+	<li>If you have made changes in the code, either execute runInGhci inside Main.hs, or recompile
+	    the executable using runServer.sh. Really you only need to be inside ghci if you are experiencing
+            the slow link time issue.</li>
+        </ul>
+    <li>
+    <li>Shutdown with ctrl-c.
hunk ./templates/run-tutorial-locally.st 28
-    <li>In practice, I usually run the app from inside ghci.
-        In the top level of the project,
-        I run ./hackInGhci.sh and then run the method "t" which does the right thing. 
-        Fortunately the linking issue has no effect inside ghci, 
-        or I would never get anything done.
-    </li>
-    <li>If you're using HAppS in a "production" application with a high load, you might want to be running an
-        executable though. Every so often when I'm not in a hurry I run the command ./runServer.sh,
+    <li>The command  ./runServer.sh,
hunk ./templates/run-tutorial-locally.st 31
-	When I see link times over 5 minutes I try to isolate the 
-        "slow" methods in a file called "Slow.hs" so that the linking is only slow when that file changes.
-        Lately I removed the Slow module, because for whatever reason linking has become fast again.
-        I dont really know why the (sometimes) slow link times but like the bug report says,
-	it probably has something to do with template haskell. 
hunk ./todo 6
+  Diagnose why I had the slow link times, and what changed to go from 10 minutes to 10 seconds
+  Start by doing binary cuts on the repo and figure out when the most dramatic improvements occurred
+  I am really bugged by the slow link time bug, and tantalized by the idea that I may have a solution,
+  or at least information that will help with diagnosing it. However, I think it's more high priority
+  to release a v3 of the tutorial, and then revisit the slow linking issue.
+
+  Make cabal install simpler by using the thing that lets you import a whole directory for the templates
+
+