View and vote on the article here: Dinah Structure and Development
Dinah Structure and Development| Category | | | Summary | 1. Installation
I'm going to describe an installation process on a Linux operating system. The BSD way may differ a bit, although I believe not much.
We need to get the following tools installed:
- Perl 5.8
- apache 1.x
- mod_Per
|
| | Body | 1. Installation
I'm going to describe an installation process on a Linux operating system. The BSD way may differ a bit, although I believe not much.
We need to get the following tools installed:[list]
Perl 5.8
apache 1.x
mod_Perl 1.x
mysql 4.1 or later
subversion (svn)
I'm not going to get into the details of the installation for these tools, they all have very detailed and useable installation guides or you can install these tools via a package manager.
The only problem that can surface here is with mysql. You need to get mysql 4.1 or later, not 4.0.x, because there are MyISAM tables used. The installation script, if used with 4.0.x, fails. So make sure you're using a 4.1 or later version of mysql-server.
Don't forget to create an username/password combination for usage in dinah and to create an empty database called "cyberarmy". Don't forget to ADD a password for already existing accounts in mysql, because without it anyone can access the database (in the case of a fresh install)!
Now, at this point, you should have all the required programs installed, i suggest creating a separate user for your dinah development environment (I will call that user "dinah" in this article).
You should now submit these commands:
# su dinah
This command masquarades you as the username you specify here.
# svn checkout https://svn.cyberarmy.net/repos/dinah/trunk
You'll need to enter an username/password combination here, which is your CyberArmy username/password. Then the subversion tool will download the up-to-date code to your system.
# cd trunk
We enter the development trunk here.
# su root
We need to run the next command as root.
# make install
Now, this will chew out a LOT of dependency problems with perl, due to missing perl modules. Hit ctrl+c to cancel the installation and issue the following command:
# cpan
This should get you to the CPAN shell. If it's not working, there is another way to do it:
# perl -MCPAN -e shell
So now, we have a list of the missing perl modules, and we're going to install them from the cpan shell. Place the module names there where it says so.
cpan> install <insert modules name here>
Beware: This can possibly break down and perl will generate a lot of errors. There will be a lot of dependencies as well. Check where the failure occurred and there might be a development library or tool missing from your system. Install the library or tool and retry the install. In the case that only a small percentage of the testing phase fails, it can be ignored quite safely; just override the test when you retry the install with this command:
cpan> force install <module name>
Once you have all of the modules installed, we can progress further.
# make install
You can now execute this command and it shouldn't indicate any missing perl modules (hopefully). This make install will guide you through the installation, after you answer a few configuration questions.
You can now drop the root privileges
# exit
The next command you should execute is:
# make config
This will basically enable you to configure your dinah version, mysql access etc.
The next step should be:
# mysql -C cyberarmy < conf/scheme.sql
You did create the cyberarmy database in mysql, right? If not, you can do it with the following command in mysql:
mysql> CREATE DATABASE cyberarmy;
Basically, at this point if you got through all the difficulties, your dinah version should be ready to run. There's only one step left to actually start it :)
# make start
It should start without errors.
Please note, your dinah instance will come with a default user, "dinah" and password "dinah" (as stated in the welcome msg).
You should change that password ASAP. By default, dinah has command level access, and new users who sign on will be troopers.
Now we're ready to get things done. :)
2. Structural overview
# ls ~/trunk/
CONTRIBUTIONS LICENSE Makefile README bin conf htdocs lib support templates test
The directory list gives you the output above.
LICENSE: The dinah license.
README: currently empty.
bin: contains the installation scripts and dinahctl.
conf: contains the configuration files for your dinah instance.
htdocs: contains mainly static html files and the images (badges, forum logo, etc)
lib: now, we have reached the truly important part of the source, the dinah codebase. This directory contains all the truly important perl packages the site is made up from. More on this later.
support: This dir contains atm only one static html file, the error page for error code 502.
templates: This directory is another important directory. It contains around 50-70% of the html code the site is made up from. That number is due to change to 100% slowly, as I'm in the process of converting the html code currently available in some older sections of the codebase (in lib/CyberArmy/Apache/My.pm and lib/CyberArmy/Apache/Forum.pm) to templatized form. Templates are good because they separate the html from the perl code, making html and perl more easily maintainable.
Now let's get back to ~/trunk/lib.
To put it short, basically the apache config (~/trunk/conf/httpd.conf) assigns various packages as handlers for various paths.
Let me give you some examples:
From httpd.conf:
<Location />
SetHandler perl-script
PerlSetVar SelectFields 'session_time,brigade,brigade_pos'
PerlHandler CyberArmy::Apache::My
</Location>
This basically assigns the frontpage to the CyberArmy module (which is THE module, more or less), and all the code is in ~/trunk/lib/CyberArmy. So inside the CyberArmy module there are packages, which are responsible for various functions, for parts of dinah, and for the CyberArmy website. CyberArmy::Apache::My translated into a direct path is ~/trunk/lib/CyberArmy/Apache/My.pm .
Packages usually can be imagined as a file, containing a part of the code responsible for a certain thing, although I have to note that multiple packages can be contained in a .pm file or inside another package, like in the example of ~/trunk/lib/CyberArmy/WWW.pm where it contains the package CyberArmy::WWW and package CyberArmy::WWW::BBCode and package CyberArmy::WWW::Utils.
Okay, so now we're familiar with how certain pieces of code are associated with certain parts of the site. The httpd.conf is the place to look if you want to find out where to look for the code, for example, driving /brigades. It's out of the scope of this article to detail every file and directory inside ~/trunk/lib/CyberArmy, or maybe it will happen in a second part of this article, but that is not certain yet.
The last part of this article will offer guidance on how and what to develop, what to develop.
3. Development
What should I develop?
Well, this is the easy part. I've got around 15 dinah related TODO items on my ToDo list, big and small.
A general rule of thumb could be to look around for things YOU would like to change. Little bugs, new features, code cleanups, etc., and then code them. If you want a new feature, it will be much harder to say no if you back it up with a patch. If you really have no idea, talk to me, wa1800z, Chawmp, or snarkles and ask for something to code. I'm 100% certain we'll have something.
How do I develop?
Well, you should have a working environment now, and you have svn, so you pretty much have everything needed.
Here is some advice, though:
- Keep your trunk updated at all times ("svn update").
- Use "svn diff > patchname.patch" to make patches from the changes you've made to the code.
- Use "svn add" to introduce new files to the subversion system if you've created a new package or template.
- Study the subversion manual in detail.
- Try to make many small changes and many small patches, separating different kinds of changes if it is possible.
- If that is not possible, or you want to create an experimental and/or large scale change(s), it is better to create your own local branch. "svk" is a great front end tool to do so. Give yourself time to get accustomed to its complexity.
Where do I send patches?
Patches go to wa1800z or Chawmp. They have the necessary admin privileges to apply them and the skills and experience to understand them. Do NOT copy-paste patches into a cMS; it is not only ugly but can mess up formatting badly! Rather, copy the filename.patch to a webserver or upload it in /files and then send a cMS to wa1800z and Chawmp where you state:
- in the subject: that it is about dinah development (and possibly the name of the patch)
- a URL to the patch
- what does it do (expected behaviour, behaviour before the patch)
- what have you done to test it
- optionally, why do you think this patch should be applied? (if it isn't obvious)
Finally, here is a little list of To-dos if you feel adventurous enough to code on a large scale:
- Convert html into valid, standard (w3c recommendation), compliant XHTML.
- Convert the current legacy html code in perl to template-based HTML (from ~/trunk/lib/CyberArmy/Apache mainly)
- Code /projects system.
If you have any questions or additions, cMS me. |
|
This article was imported from zZine. (original author: comet)
There are no replies to this post yet.
|