yesod-bin
The yesod helper executable.
Version on this page: | 1.6.2.3 |
LTS Haskell 21.25: | 1.6.2.2@rev:1 |
Stackage Nightly 2024-09-07: | 1.6.2.3@rev:1 |
Latest on Hackage: | 1.6.2.3@rev:1 |
yesod-bin-1.6.2.3@sha256:ea000b0e4385c7e47d3175d39e4e3f7c49b2205ddc866ac6b243e77dcbe1f43f,2770
Module documentation for 1.6.2.3
There are no documented modules for this package.
yesod-bin: the Yesod executable
This executable is almost exclusively used for its yesod devel
capabilities, providing a development server for web apps. It also
provides some legacy functionality, almost all of which has been
superceded by functionality in the
Haskell Stack build tool. This README will
speak exclusively about yesod devel
.
CAVEAT There may be some issues using yesod devel
in Docker-enabled
projects. See comment on
Github.
Development server
The development server will automatically recompile your application whenever you make source code changes. It will then launch your app, and reverse-proxy to it. The reverse proxying ensures that you can connect to your application on a dedicated port, always get the latest version available, and won’t get dropped connections when the app isn’t yet ready. Instead, you’ll get some very motivating messages:
Common workflows
The standard Yesod scaffoldings are configured to work with yesod devel
out of the box (though see below for non-Yesod
development). For the most part, from within your application
directory, you’ll just want to run:
stack build yesod-bin
stack exec -- yesod devel
This will install the corresponding version of the yesod
executable
into your currently selected snapshot, and then use that
executable. (Starting with version 1.5.0, you can be more lax and use
a yesod
executable compiled for a different snapshot. Once 1.5.0 is
more widespread we’ll probably update these instructions.)
Some other common questions:
- If you want to control which port you can access your application
on, use the
--port
command line option, e.g.stack exec -- yesod devel --port 4000
. Changing your port inside your source code will not work, because you need to change the reverse proxying port. - If you want to run a command after each successful build, you can
use
stack exec -- yesod devel --success-hook "echo Yay!"
- If for some reason you want to disable the reverse proxy
capabilities, use
stack exec -- yesod devel --disable-reverse-proxy
How it works
The workflow of the devel server is pretty simple:
- Launch a reverse proxy server
- Use Stack file-watch capability to run a build loop on your code, rebuilding each time a file is modified
- Have Stack call
yesod devel-signal
to write to a specific file (yesod-devel/rebuild
) each time a rebuild is successful - Each time
yesod-devel/rebuild
is modified:- Kill the current child process
- Get a new random port
- Tell the reverse proxy server about the new port to forward to
- Run the application’s devel script with two environment variables
set:
PORT
gives the newly generated random port. The application needs to listen on that port.DISPLAY_PORT
gives the port that the reverse proxy is listening on, used for display purposes or generating URLs.
Now some weird notes:
- The devel script can be one of the following three files.
yesod devel
will search for them in the given order. That script must provide amain
function.app/devel.hs
devel.hs
src/devel.hs
- Unfortunately, directly killing the
ghc
interpreter has never worked reliably, so we have an extra hack: when killing the process,yesod devel
also writes to a fileyesod-devel/devel-terminate
. Your devel script should respect this file and shutdown whenever it exists. (It may be fixed in 1.6.0.5.) - If your .cabal file defines them,
yesod devel
will tell Stack to build with the flagsdev
andlibrary-only
. You can use this to speed up compile times (biggest win: skip building executables, thus the namelibrary-only
).
If that all seems a little complicated, remember that the Yesod scaffolding handles all of this for you. But if you want to implement it yourself…
Non-Yesod development
If you’d like to use the yesod devel
server for your non-Yesod
application, or even for a Yesod application not based on the
scaffolding, this section is for you! We’ve got a
sample application in the repository
that demonstrates how to get this set up. It demonstrates a good way
to jump through the hoops implied above.
One important note: I highly recommend putting all of the logic in
your library, and then providing a develMain :: IO ()
function which
your app/devel.hs
script reexports as main
. I’ve found this to
greatly simplify things overall, since you can ensure all of your
dependencies are specified correctly in your .cabal
file. Also, I
recommend using PackageImports
in that file, as the example app
shows.
Changes
ChangeLog for yesod-bin
1.6.2.3
- Support optparse-applicative-0.18 #1829
1.6.2.2
- Support Cabal 3.8 #1769
1.6.2.1
- Support Cabal 3.6 #1754
1.6.2
- aeson 2.0
1.6.1
Added command line options cert
and key
to allow TLS certificate and key files to be passed to yesod devel
#1717
1.6.0.6
Fix the add-handler
subcommand to support both the old default routes filename (routes
) and the new one (routes.yesodroutes
) #1688
1.6.0.5
- Use process groups to ensure GHC is killed on Ctrl-C #1683
1.6.0.4
- Support Cabal 3.0
1.6.0.3
- Support Cabal 2.2 #1151
1.6.0.2
- Fix broken support for older http-reverse-proxy
1.6.0.1
- Support for http-reverse-proxy 0.6
1.6.0
- Upgrade to conduit 1.3.0
- Remove configure, build, touch, and test commands
1.5.3
- Support typed-process-0.2.0.0
1.5.2.6
- Drop an upper bound
1.5.2.5
- Support for
add-handler
when modules are insrc/
directory #1413
1.5.2.4
- Cabal 2.0 support
1.5.2.3
- Fix race condition which leads dev server to stay in compilation mode. #1380
1.5.2.2
- I guess
--no-nix-pure
implies Nix… sigh #1359
1.5.2.1
- Use
--no-nix-pure
#1357
1.5.2
- Fix warnings
1.5.1
- Add
--host
option toyesod devel
1.5.0.1
- Fix build failure
1.5.0
Rewrite of yesod devel
to take advantage of Stack for a simpler codebase.
Advantages:
- Does not link against the ghc library, so can be used with multiple GHC versions
- Leverages Stack’s ability to check for dependent files, which is more robust than what yesod devel was doing previously
- Seems to involve less rebuilding of the library on initial run
Disadvantages:
- Lost some functionality (e.g., failure hooks, controlling the exit command)
- Newer codebase, quite likely has bugs that need to be ironed out.
1.4.18.7
- Actually release the changes for #1284
1.4.18.6
- Fix support for GHC 8.0.1 #1284
1.4.18.5
- yesod-bin: Make it build with latest optparse-applicative #1282
1.4.18.4
- Link yesod-bin with wxneeded on OpenBSD. #1281
1.4.18.3
- Adding a new handler adds it under wrong stanza #1273
1.4.18.2
- Work around change in behavior in newer optparse-applicative (mailing list discussion)
1.4.18.1
- error handling when checking for stack binary #1219
- GHC 8 support
1.4.18
- Disable
yesod test
when using Stack #1198
1.4.17
- Fully remove the
yesod init
command
1.4.16.1
- Workaround for wai#478
1.4.16
- Some updates for better reverse proxying yesod-scaffold#114
1.4.15
- Deprecate yesod init
1.4.14
- Fix order of -package-db arguments to runghc #1057
1.4.13
- Enable stack with yesod keter #1041
1.4.12
- Devel server: have to type quit to quit
1.4.11
- Add support to
yesod devel
to detect and useGHC_PACKAGE_PATH
. This makesyesod devel
compatible withstack
, just run:stack exec -- yesod devel
.
1.4.10
- Scaffolding update
1.4.9.2
- Collapse paths in keter bundles, see mailing list thread
1.4.9
- Command line options for
yesod init
#986
1.4.8
- Drop system-filepath
1.4.7.2
- Scaffolding updates, including fix for #982
1.4.7
- GHC 7.10 support
1.4.6
- Add TLS support to
yesod devel
#964
1.4.5
- add a switch to yesod to skip deploying a .keter with copy-to #952
1.4.4
- Add and process Keter option ‘extraFiles’ #947
1.4.3.11
- Disregard proxy environment variables in yesod devel #945
1.4.3.10
- Allow blaze-builder 0.4
1.4.3.9
- Scaffold update: minimal scaffold uses yesod-core instead of yesod yesodweb/yesod-scaffold#65
1.4.3.8
- Scaffold update: fix 404 for missing sourcemap
1.4.3.6
- Scaffold update: use
addToken
instead ofaddNonce
1.4.3.5
- Fix add-handler putting two routes on one line #922
1.4.3.4
Scaffolding updates:
- Improve
DevelMain
support - Wipe out database during test runs
- Convenience
unsafeHandler
function - Remove deprecated Chrome Frame code
1.4.3.3
More consistent whitespace in hamlet files in scaffolding #50
1.4.3.2
add-handler adds arguments too #898
1.4.3
Add the minimal scaffolding
1.4.2
Scaffolding updates:
- Import.NoFoundation
- Explanation of static files in Settings.StaticFiles
- Explanation of environment variables in settings.yml
1.4.1.2
No args passed in keter.yml
1.4.1
Significant update to the scaffolding.
1.4.0.9
Allow devel.hs to be located in app/ or src/ subdirectories.
1.4.0.8
Updated postgres-fay scaffolding for yesod-fay 0.7.0
1.4.0.7
Fix a bug in yesod devel
when cabal config has tests: True
#864