From 3c9fb1253add3e8d3b8ca8550d47daef21940c05 Mon Sep 17 00:00:00 2001 From: Dave Cross Date: Thu, 12 Jan 2017 15:21:09 +0000 Subject: [PATCH] Added more to the first chapter --- chapters/basic-app.md | 136 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) diff --git a/chapters/basic-app.md b/chapters/basic-app.md index 4198654..1334cd7 100644 --- a/chapters/basic-app.md +++ b/chapters/basic-app.md @@ -89,3 +89,139 @@ port 5000. If you open a web browser and visit http://localhost:5000/ you will see your web application looking like this: ![](img/step01.png) + +Of course, the program doesn't do anything useful yet (that's what the +rest of the book is for) but it runs. And that's a good start. + +## Files + +Let's take a closer look at some of the files that the `dancer2 gen` +command created for us. + +In the top level directory, you will find the following four files: + +* **cpanfile** is a file that various parts of the Perl toolchain can + use to ensure that a user has installed all of the modules that are + required to run your application. As our app uses more modules, we + will need to add information to this file. +* **Makefile.PL** is a file that will be familiar to anyone who has + installed Perl modules manually. Running this file in the correct + environment will generate a `Makefile` which can be used to test and + install our application. This is another file which we will need to + keep up to date as we add things to our application. +* **MANIFEST.SKIP** is another file that the Perl toolchain uses. It + lists files that don't need to be included in the distribution + tarball for our application. Usually, you'll find that the version + that has been created will handle all of your requirements, so + there's rarely any need to edit this. +* **config.yml** is the main configuration file for our + application. It is in YAML (YAML Ain't a Markup Language) format + which makes it simple to read and edit. We'll need to make various + changes to this file during the development of our application. + +Then there are a few subdirectories. We'll look at some of these in +more detail in the following chapters but, for now, we'll just +describe the contents in high-level terms. + +* **public** contains files that will be served directly by our + application. These are generally static files like images or CSS + files. +* **t** contains tests for our application. We'll try to add new tests + to this directory whenever we add new features to our application. +* **lib** is where (most of) the magic happens. This is where you will + add the Perl code that drives your application. We'll be doing a lot + of work in this directory. +* **views** contains the templates that are used to create the web + pages that the users see. We will be making a lot of changes in this + directory in the next chapter. +* **environments** contains two further configuration files called + `production.yml` and `development.yml`. Dancer apps can run in + different modes and these extra configuration files can be used to + make the app work in slightly different ways in different + environments. If you look at the two files, for example, you will + see that logging is configured differently in them. +* **bin** contains the main application file. This is a ".psgi" file + instead of the more usual ".pl" file as Dancer apps are all built on + top of the "Perl Server Gateway Interface". I'll explain a little + more about that later on. + +There are a lot of files there. And we'll look at many of them in more +detail as we develop the app. For now, I just wanted to look at two of +them - the main application file and the Todo.pm library. The main +application file (called `bin/app.psgi`) looks like this: + + #!/usr/bin/env perl + + use strict; + use warnings; + use FindBin; + use lib "$FindBin::Bin/../lib"; + + use Todo; + Todo->to_app; + +There's not very much to it. And most of that is boilerplate. Let's +look at each line in turn. + + #!/usr/bin/env perl + +This is the "shebang" line. It's a Unix feature. If the first line of +an executable Unix (or Linux) file starts with `#!` then the Unix +shell assumes that the rest of the line contains the path to a program +that should be used to execute the code. It's common to see shebang +lines like `#!/usr/bin/perl`, but that assumes that the Perl compiler +is in a specific directory. Using the `env` program means that the +shell will search the user's path for the first Perl compiler that it +can find. + + use strict; + use warnings; + +These two lines should be in every Perl program that your write. They +are basically "safety nets" which let you know if you're writing code +that looks a bit strange. + + use FindBin; + use lib "$FindBin::Bin/../lib"; + +These two lines tell Perl to add our app's `lib` directory to the list +of places where it looks for modules. The "FindBin" module is a +standard tool that is included with every Perl installation. Once +FindBin is loaded, you have access to a variable called +`$FindBin::Bin` which contains the name of the directory containing +the currently executing program. That's `Todo/bin`, so we append +`../lib` in order to get `Todo/lib`. We pass all that to `use lib` +which is a Perl standard library tool which adds any strings it is +given to the library search path. That allows us to then include the +next line. + + use Todo; + +As mentioned above, `Todo.pm` is the main library for our +application. This line finds and loads this library. And that only +succeeds because we've added `lib` to the library search path with the +FindBin magic above. + + Todo->to_app; + +All of that was just preamble which allows us to run the important +line. As we will see later, a PSGI application needs to be a reference +to a subroutine. And Dancer gives our application class a method +called `to_app` which returns the required reference. The PSGI +environment (usually `plackup` while we're developing the app) +arranges to call that subroutine with the correct parameters. + +So there's not much there. Surely the main library code must be a lot +more complex. Well, not really. Here is `Todo.pm`. + + package Todo; + use Dancer2; + + our $VERSION = '0.1'; + + get '/' => sub { + template 'index'; + }; + + true; +