Choose a project name
The first step in setting up a new build-web project is to decide on a name
for the project. Typically this is the same name you will use for the directory where the project
will reside. The default setup is to place the project directory as a sibling of the
build-web directory. In this example, myProject will be
the name of the project we are setting up.
Copy the build-web/srce/examples/project directory to where you wish your project
to be located and rename it to myProject
Copy the build-web/srce/examples/child-project directory to where you wish your project
to be located and rename it to myProject.
Choose a Source Web Directory name
The convention is to use a variation on the project name as the Source Web Directory
name. In our example, the Source Web Directory name will be myProject-srce. Since
all occurences of /myProject-srce/ will be replaced according to the dirmap scripts,
this choice of name will reduce the likelihood that any other string in your source files will
be accidentally modified.
The default project uses the myProject/srce directory to contain the raw Source.
Choose the output directories
The default project defines two BUILDTYPES: dev and prod.
Each BUILDTYPE uses a distinct set of directory map scripts and output directories. By
appropriately editing the Makefile for the project and creating the appropriate
directory mapping scripts, it is a possible to add additional BUILDTYPEs to suit your needs.
myProject/dest-dev and myProject/dest-prod are used to contain the
development version and production versions of the Destination output respectively.
There may be circumstances where you wish to change the location of the dest-xxx output
directories. This can be most useful when multiple developers share a single output directory
on the same web server. You can change the location of the output directories either by:
At this point you will need to choose the Destination Web Server path for your
Development output. A choice that I often make is to use the
style /dev/myProject for all development output. This allows me to consolidate
all development versions of web sites in a single location on my web server. This choice is
yours however.
The choice for the Destintation Web Server path for your Production output depends on how and where it will be hosted on your production server. It can be targetted at the root directory of the server or it can be targetted at a subdirectory depending on your needs.
Configure any child projects.
If child projects are to be included in this project you will need to change the related variables and targets in myProject/Makefile to correspond to the child project you are including.
If you are not including child projects, then you should remove the child project related variables and targets in the Makefile.
Note that if you have a child project that is to be used by many different build-web projects
on the same web server, it is more appropriate to simply refer to the child project's location
via it's Source Web Directory (/child-project-srce/) and to build the child project
separately. This will allow many projects to refer to the same project without having to contain
duplicate copies of the child in each project. You will still have to place a directory mapping
for /child-project-srce/ in your dirmap*.pl scripts.
If your child project has not already been set up, you will need to do so before building it's parent.
Edit myProject/Makefile, and dirmap*.pl
Next you will need to customize the Makefile and dirmap*.pl scripts
for your project. Edit Makefile and dirmap*.pl and
replace all occurences of /example-project-srce
with the name of your Source Web Directory, e.g. myProject-srce.
Edit the appropriate dirmap-dev.pl and dirmap-prod.pl as appropriate
to add the mapping from the Source Web Directory path to the Destination Web Directory.
A Child Project is a separate build-web project that you wish to be built and included
in the output of your project. This is most useful when including script libraries or other projects
which can be reused from one project to another. Child Projects can also be used to split very
large projects into more manageable pieces. The default Makefile in the project-template
is setup to have a single child project.
If your project contains one or more Child Projects, then you must edit the Makefile
to change the references to child-project to the name of your child project. You should
duplicate the child project sections of the Makefile for each of your Child Projects. You
will also have to edit the corresponding dirmap-child-project-dev.pl and dirmap-child-project-prod.pl
scripts to reflect the correct Source Web Directory name mapping for the Child Project.
Next you must customize the template.html and template-nomenu.html files
in the myProject/srce directory to fit your needs. Samples are available to be customized.
[OPTIONAL] Set up the virtual Web Server path to your project's physical source directory.
Setup a virtual path /myProject-srce/ on your web server to point to the
raw Source Web Site at myProject/srce directory. Setup the myProject-srce
virtual path to support Server Side includes for regular HTML files so that you can view the results
of the SSI's on the raw source.
Note if more than one developer is sharing the same physical web server, or if for some reason you have multiple versions of the same build-web project, then you will need to set up a web server operating on a different port and which uses your physical source directory as it's root.
For example, the source physical directory will be available as:
http://server:port/myProject-srce/.
Note to support multiple developers on the same physical computer, you will need to set up virtual web servers for each developer so that they can have their own private version of the Raw Source Web project.
Set up Web Server access to your output directories.
The easiest approach for development versions of web sites is to soft link into your web servers document tree (under /dev/ for example) and write your output directly.
For production version you can follow a similar approach if the production web site lives in a subdirectory of your production server. However if your production version must live on the web server's root then you must set up a virtual web server on a different port in order to view the production version.
With this setup, you will be able to view the following:
Code your Web project in myProject/srce.
Be sure to use web directory paths composed of the Source Web Directory names for your project and any Child projects in the form /myProject-srce/ and /.
Build Your Web Project
| Build Web Home |