Frequently Asked Questions
- How can I report a bug in Snap?
- What are some good examples of Snap applications?
- Is anyone using Snap in production?
- Why can’t I install Snap?
- How do I run my app in development mode?
- How do I enable SSL?
- Why do I get a “cannot find normal object file” error when building Snap?
- Why doesn’t Heist display templates?
- How do I do looping in Heist?
- Why can’t I nest a
- How can I get debugging output?
- Why does throughput plummet when I run snap with multiple cores?
- How do I fix the libstdc++ error?
- Can I develop with Snap on Windows?
- How can I help?
- Where did the libev backend go?
How can I report a bug in Snap?
Found a bug in Snap? Please create a ticket on our issue tracker.
What are some good examples of Snap applications?
HSnippet is a non-trivial app built using Snap.
A simple example project implementing a Starcraft Blog.
This website serves everything using Snap.
Is anyone using Snap in production?
Yes! Here is a list of sites that we know of that use Snap. Let us know if you know of others:
Piperka uses Snap and serves Heist templates.
Everything at Fynder is powered by Snap.
Soostone uses Snap for their entire web stack across multiple products with applications ranging from front-end UIs to high volume data/analytics APIs.
housetab.org - a webapp for sharing expenses.
JCU a web-based Prolog environment.
howistart.org a tech tutorial resource.
http://snapframework.com (this site)
Why can’t I install Snap?
First, make sure you have
"$HOME/.cabal/bin" at the beginning of your path.
You may have an old version of Cabal. Try running
cabal update && cabal install Cabal. After this,
cabal --version should say that you’re using version 18.104.22.168 of the Cabal library or higher. After you do this, try installing Snap again.
If you’re getting getting a different error involving dependencies that are not available, one of the best ways to fix the problem is
rm -fr ~/.ghc and then try installing again. This deletes all your user-installed packages and starts fresh from scratch. Obviously this is a suboptimal solution, but unfortunately, due to current limitations of Cabal it is pretty much a fact of life when doing significant Haskell development. It will probably take 15-20 minutes to rebuild everything, but it has a high rate of success for a variety of different dependency problems. Another alternative is to use cabal-dev instead of cabal-install.
If you are an OpenBSD user, check out the guide Jim Razmus wrote on installing Snap.
How do I run my app in development mode?
Running Snap in development depends on which version of Snap you are using:
Snap 0.9.1.1 upwards
If you used
snap init to create your project, you simply need to build your project with the
cabal clean; cabal install -f development
If you’ve already built your application without development mode, it’s important to run
cabal clean first, as above.
If you didn’t use
snap init to start your project, or are porting old code, the general idea is to build against the
snap-loader-dynamic library and launch your server with the
loadSnapTH function it provides. For more information, we recommend running
snap init from the
snap-templates package and looking at the generated code.
Earlier versions of Snap
To get development mode you first need to build snap with
cabal install snap -fhint
and then build your application with
-fdevelopment. If you don’t do this, you’ll get
Could not find module 'Snap.Loader.Devel'.
How do I enable SSL?
First, you need to install snap-server with
-fopenssl. If you have already installed snap-server, you might want to uninstall it first with
ghc-pkg unregister -f snap-server to avoid potential version conflicts.
Once you have done that, run your application as follows using values appropriate to your setup.
./app --ssl-port=443 --ssl-cert=cert.pem --ssl-key=key.pem --ssl-address=0.0.0.0 --ssl-chain-cert=False
If you are setting the server configuration in your Haskell code, you need to make sure that you set a value for all five of the SSL config fields.
Why do I get a “cannot find normal object file” error when building Snap?
If you try to build Snap in profiling mode, sometimes you will encounter this error:
cannot find normal object file `dist/build/snap/snap-tmp/Snap/StarterTH.o'
GHC has a bug in which it gets confused about where to look for object files when a) using template haskell, and b) compiling in profiling mode. The workaround is to compile the library without profiling, then reconfigure and rebuild:
$ cabal configure
$ cabal build
$ cabal configure -p
$ cabal build
Why doesn’t Heist display templates?
The most common problem we’ve seen is that you have “.tpl” included as part of your template name. Heist automatically adds the “.tpl” extension, so you shouldn’t include it.
How do I do looping in Heist?
Heist is different from a lot of other template systems in this regard. You actually don’t do any looping in Heist. You do your looping in Haskell. See http://softwaresimply.blogspot.com/2011/04/looping-and-control-flow-in-heist.html for more information.
Why can’t I nest a
div in a
p with Heist?
This is not allowed in HTML. Suppose you write HTML that look like the following:
It may look like you’ve nested a
div element inside of a
p element, but that isn’t what really happened. In fact, the start tag
<div> caused the paragraph to end. The
div element occurs after the
p element. Finally, the closing
</p> tag doesn’t match anything, and most web browsers will discard it.
Heist HTML templates parse things the same way, but since templates are expected to be valid HTML 5, the invalid closing tag causes a parse error. Heist prefers to give you the error sooner, rather than surprising you with an unexpected document structure in your splices.
The best answer is to just place the
div element at the top level beside your paragraphs. That’s what you were doing anyway, so it won’t break anything.
Remember that you can disable HTML 5 parsing by naming your templates with the suffix
.xtpl, so if you don’t want Heist to implicitly close paragraphs and follow other HTML 5 specific rules, you can follow XML document rules instead.
Why does throughput plummet when I run snap with multiple cores?
The parallel GC introduced in GHC 6.10 doesn’t seem to play very well with Snap. If you turn parallel GC off (using the “
-qg” flag, e.g. “
./foo-website +RTS -N -qg”) throughput should improve dramatically.
How can I get debugging output?
With recent (>0.2.12) snap-core, if you set the environment variable
DEBUG=1 then Snap will produce debugging output to stderr. There is a very slight performance penalty associated with this feature; if you are in a production setting and require speed at all costs, you can disable debug output when building
snap-core by passing the
no-debug flag to
$ cabal install snap-core -fno-debug
How do I fix the libstdc++ error?
In some cases (most notably on MacOS), people have encountered this error when building snap:
Loading package double-conversion-0.2.0.1 ... <command line>: can't load
.so/.DLL for: stdc++ (dlopen(libstdc++.dylib, 9): image not found)
The issue is supposed to be fixed in GHC 7.4, but until then rebuilding blaze-textual with the following command has been known to work.
$ cabal install blaze-textual --reinstall -fnative
Can I develop with Snap on Windows?
Yes! Snap 0.5.5 and Snap 0.6 have been tested to work on Windows 7 using Haskell Platform 2011.2.0.1.
To compile the Snap 0.6 package on Windows, you will need to apply the work-around mentioned in FAQ entry How do I fix the libstdc++ error?.
Note that in order to quit a running Snap app on Windows, you need to press
How can I help?
Use Snap to build real websites.
This is perhaps the best way to help. Let us know what issues you encounter and work on fixing the ones you care about most. If you are unable to fix a problem, you can still help by writing an automated test case that detects the problem.
It’s also very likely that infrastructure you create in the course of building a real website can be generalized and merged into Snap. Much of Snap’s higher-level functionality should become more evident as we find code patterns common to real-world Snap websites. Communicating real-world Snap development experiences to us is a great way to contribute to this effort.
Develop automated memory leak and performance regression testing.
Currently our top priority is working out correctness and performance issues in the server. We have a CI build server that automatically runs all our test cases, but we don’t have an automated system to test for performance and memory leaks. This would be a very helpful addition.
Improve test cases and code coverage.
While not an exotic task, expanding our test suite can contribute significantly to the stability of the project.
Improve documentation and tutorials.
It’s easy for documentation to get out of date. We try to keep it up-to-date, but we can always use more eyes to catch things that slip through the cracks.
Where did the libev backend go?
Before Snap 0.9, you could build
snap-server with the
-flibev backend to use the libev library for I/O multiplexing. However, now that all recent versions of GHC come with an I/O manager that uses
epoll() on unix platforms, libev is no longer significantly faster than stock Haskell I/O and support was removed in version 0.9 in order to reduce our maintenance burden.