Frequently Asked Questions

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.

• Janrain uses Snap to serve their user management platform which is used by a number of popular websites.

• 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.

• lpaste, a simple Haskell pastebin. A blog post about it is here and the source code is hosted here.

• Darcs Hub is a nifty GitHub-like source code hosting site for Darcs (source code here).

• 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 1.8.0.4 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.

If you’re still having trouble, please email our mailing list or contact us on our IRC channel (#snapframework on freenode).

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 development flag:

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 -fhint:

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:

src/Snap/Starter.hs:1:0:
     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:

<p>
  <div>
    Some content
  </div>
</p>

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:

$ 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 Ctrl+C twice.

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.