HOWTO Develop Aiki Framework

From Aikiframework wiki

Jump to: navigation, search

Below are some setups for developing Aiki Framework core software. Note, this is different from developing inside of Aiki Framework. There are also different ways of developing the system. Below, we try to outline some of those best practices.

Before you start coding read Coding Style and Coding Art

Contents

General

Launchpad

We use Launchpad for managing the project's code, bugs, and feature requests.

Linux Ubuntu 10.04 (Debian-based)

Requirements

These instructions are for Debian/Ubuntu Server tested on Ubuntu 10.04

Bazaar

sudo apt-get install bzr

Build tools

sudo apt-get install autoconf build-essential libtool automake desktop-file-utils zip unzip gnupg-agent

LAMP

LAMP is an acronym for Linux, Apache, MYSQL, and PHP. Your system might have the full LAMP stack installed, but if not, then here is a quick tutorial in Ubuntu to get you started.

https://help.ubuntu.com/community/ApacheMySQLPHP

NOTE: In Ubuntu, and some other Linux distributions, you need to make sure the rewrite module is linked properly and then restart apache. This is tested on Ubuntu 11.04: 

sudo ln -s /etc/apache2/mods-available/rewrite.load /etc/apache2/mods-enabled/
sudo apachectl restart

gpg-agent

To build the package release, you need to have generated a gpg key and have gpg-agent running so that you can sign the releases.

  1. Use GnuPG to generate a key
  2. Set your key as the default key in your ~/.bashrc as per the above instructions.
  3. Set gpg-agent running for your sesesion 
killall -q gpg-agent
eval $(gpg-agent --daemon)
source ~/.bashrc

You'll need to do this prior to running make or sudo make install in the instructions below.

PHPUnit

Aiki Framework and its sites use PHPUnit for their testing suite. You can run the unit tests as an Aiki developer or adapt them for your own site.

See Installing PHPUnit 

sudo apt-get install php-pear
sudo pear channel-update pear.php.net
sudo pear upgrade-all
sudo pear channel-discover pear.phpunit.de
sudo pear channel-discover components.ez.no
sudo pear channel-discover pear.symfony-project.com
sudo pear install -a phpunit/PHPUnit

Guidelines

There is not one right way to develop on the core. We've tried to document different ways of developing the Aiki Framework Core. There are some best practices we try to follow in committing code.

  • We are sticking a bit more at present, to the SVN style of development while our developer community is a bit smaller. However, if doing bigger features, developers are encouraged to do big changes on a branch.
  • Never commit broken code
  • Always make verbose comments when committing code
  • Always bzr update before doing bzr push to the main lp:aikiframework repository

Suggested Tools

Coding Style

  • We use 4 spaces as indentation (default GNU/Emacs indentation style)
  • 80 characters is maximum width of column
  • spaces around parentheses except function invocation
  • curly braces in the same line as statements
  • one space before opening curly braces
  • spaces around operators
  • one space after comma (except when last character in the line)
    • if operator is the last character there should not be space after operator
    • if operator is first character in line there should be no more spaces, then indentation, before operator
  • in other places there should be no spaces 
  if ($foo == $bar) {
     foo("foo", "bar");
  }
  
  while ($foo == false) {
     x += 10;
  }
  
  if ($foo == "bar" && $a == "bar") {
  }
  
  function getUrl($name, $url) {
     return '<a href="' . $url . '">' . $name . '</a>';
  }
  
  switch ($foo) {
  case 1:
      foo(10);
      break;
  }
  
  $foo = array("foo" => "lorem", "bar" => "ipsum");
  • one space after the colon but not before (javascript) 
   var foo = {
      foo: "lorem",
      bar: "ipsum",
      baz: "dolor"
   };
  • classnames are capitalized
    • class AikiFramework {}
  • public methods in a class are camelcase
    • public function doSomethingNow() {}
  • static and private function names are standard with underscore
    • function this_is_function()

Here is a good example on naming classes, functions, and variables: 

NamespaceName
ClassName
CONSTANT_NAME

publicMemberFunctionName
_protectedMemberFunctionName
_privateMemberFunctionName

public_static_member_function_name
_protected_static_member_function_name
_private_static_member_function_name

_member_name
$_member_name
function_name
variable_name
$variable_name

Coding Art

One day, a stranger will read your code, You!

Have you forgotten where you left your keys last night? Now, imagine, you have to check your code written 3 months ago. Remember, writing code is only 30% of work, the rest is: maintain, document and find bugs.

The best documentation is the code

Write the code in a way that anybody can understand it: use clear names for functions, variables, method. A clear name must reveal what do this function, o what contains this variable.

Divide code, divide problems

A system divided in parts can be understand without understand all parts. A big problem can be divided in smaller problems.

Don't document the obvious

Use documentation only to note: steps (what will be do or is done), tips, cautions, regular expression. Make it useful.


Different Setups

There isn't one right way to develop since Aiki can work on so many different system types, and people can help how they feel best. Below are some of the developers of Aiki and how they recommend to develop on Aiki Core.

How to package a release

  • Pull the latest code 
bzr lp-login YOURUSERNAME

bzr checkout lp:aikiframework aikiframework
  • Make sure the version number of aikiframework is updated 
vim /path/to/aiki/bootstrap.php
  • Zip up the folder 
cd /path/to/aiki
cd ..
zip -r /path/to/zip/aiki-VERSION.zip /path/to/aikiframework

Rejon' Setup on Fedora 15 Linux

The goal of my setup is to use the src directory as the running instance of aiki framework and the development version of aiki framework. I'm running:

  • Fedora 15
  • LAMP Stack
  • Text Editor: vim
  • Using all the standard tools

I like to develop on my own local system. I setup the system so that aiki.localhost is my running instance on my local system, so that the root of this aiki instance is like any website.

  • Open gnome-terminal
  • edit /etc/hosts 
sudo vim /etc/hosts
  • add to the localhost line aiki.localhost and our server/computer's name, mine is slowtop. Here are my defaults: 
127.0.0.1       localhost.localdomain localhost
  • Here is what I added: 
127.0.0.1       localhost.localdomain localhost aiki.localhost slowtop
  • save the file, in vim type: 
:wq
  • Now its time to create apache configuration file. I'm starting this from default Fedora 15 apache configuration.
  • Edit /etc/httpd/conf/httpd.conf 
vim /etc/httpd/conf/httpd.conf
  • Uncomment the line 
# NameVirtualHost *:80
  • To: 
NameVirtualHost *:80
  • At the end of the document (in vim, can type 0 + G to go to end of the document, type i to insert) 
# Include the virtual host configurations:
Include /etc/httpd/sites-enabled/
  • Save the file 
:wq
  • Create the folder /etc/httpd/sites-enabled/ and /etc/httpd/sites-available/ 
sudo mkdir /etc/httpd/sites-enabled/
sudo mkdir /etc/httpd/sites-available/
cd /etc/httpd/sites-available
  • Create the aiki.localhost file 
<VirtualHost *:80>
    ServerAdmin YOUREMAIL
    ServerName aiki.localhost
    ServerAlias www.aiki.localhost
    DocumentRoot /srv/www/aiki.localhost/public/
    <Directory /srv/www/aiki.localhost/public/>
        AllowOverride All
    </Directory>
    ErrorLog /srv/www/aiki.localhost/logs/error.log
    CustomLog /srv/www/aiki.localhost/logs/access.log combined
</VirtualHost>
  • Save the file 
:wq
  • Create a symlink to site-enabled 
ln -s /etc/httpd/sites-available/aiki.localhost /etc/httpd/sites-enabled/aiki.localhost
  • Create standard server setup 
sudo mkdir -p /srv/www/aiki.localhost/public
sudo chown -R rejon:rejon /srv/www/aiki.localhost
sudo mkdir -p /srv/www/aiki.localhost/logs
  • Run from commandline: 
sudo /etc/init.d/httpd reload
  • Navigate to your working directory 
cd /srv/www/aiki.localhost/public
  • Login to launchpad 
bzr lp-login rejon
  • Pull latest Aiki Framework code 
bzr checkout lp:aikiframework aikiframework
  • Setup your mysql database and fill in the required fields to setup aiki
  • Edit some files such as /srv/www/aiki.localhost/public/aiki.php
  • Check to see your changes 
bzr stat
  • If there are changes, then you can commit them. One thing to make sure is that in this centralized SVN style approach to using bzr, make sure to update your repository from the master/centralized one: 
bzr update
  • Then you are ready to commit your changes: 
bzr commit -m "committing changed files"
  • Repeat the process.
  • Later we will detail a process for dumping your database and getting those changes out.

Bassel's Setup

  1. open eclipse
  2. I'm already logged in to everything including bzr and /admin so move to 3
  3. open firefox to http://localhost/aikiframework/admin
  4. open another tab of firefox to http://localhost/aikiframework
  5. add some test widget to test method on step 6
  6. open a file on eclipse, modify -> save -> refresh firefox
  7. bzr commit -m "some changes"
  8. bzr push

Brad's Mac OS X Setup

Install MAMP

My process begins with installing and configuring MAMP for testing on the localhost.

  • I set my apache Document Root to be my /Sites directory
  • For information about MAMP configuration, see this article
  • You'll also need to specify MAMP Mysql as the default Mysql for your mac to use, you can do this with a symbolic link:
    • From Terminal, type: sudo ln -s /Applications/MAMP/Library/bin/mysql /usr/local/bin/mysql
  • The final step is ensuring Apache knows where to find Aiki's config file:
    • Open /Applications/MAMP/conf/apache/httpd.conf (backup this config file before changing!)
    • Add the following at the very end of the file:
      • Include /Applications/MAMP/conf/apache/z-aiki.conf
        • Note: MAMP will now not start up if it doesn't find this Aiki config file, so either create a blank file called z-aiki.conf or install Aiki before starting up MAMP

Public/Private SSH Keys

Once MAMP is up and running & serving pages from your machine, it's time to generate some ssh keys.

  • Drupal.org has a great tutorial for ssh public & private key generation via Terminal.

After your keys are generated, Launchpad will need your public key.

  • You should be able to add your newly-generated public key via your launchpad.net/~username page

Install Bazaar

Bazaar will be the primary means to communicate between Launchpad (where the Aiki source code is maintained) and your code revisions

Install Additional Unix Commands

The scripts in this Aiki Install rely on a few Unix commands that aren't included in Mac os x by default:

  • Install XCode & X11: // needed to install MacPorts
    • Insert the OS X install disc & select 'Optional Installs', followed by the XCode pkg (requires ~3 gigs of space)
    • The X11 software is also found on the OS X install disc, with the other optional installs (requires ~30 mb of space)
  • Install MacPorts:
    • Visit the following link & download the .dmg & install MacPorts : http://www.macports.org/install.php
    • Be sure & update MacPorts, upon install:
      • From Terminal, type: sudo port -d selfupdate // Be sure & disable any firewall software like PeerGuardian!
  • Install autoconf
    • From Terminal, type: sudo port install autoconf
  • Install automake
    • From Terminal, type: sudo port install automake
  • Install GPG
    • From Terminal, type: sudo port install gnupg

Get Aiki Framework Source onto your Mac

Now you should be ready to login to Launchpad & begin working with Aiki Framework!

In Terminal, type:

  • bzr lp-login {your-username} //identifies you to Launchpad (ssh key needed, here)
  • bzr branch lp:aikiframework //downloads a copy of Aiki's source on your Mac

Make changes to Aiki's Source

Edit files, as necessary

Packaging, Configuring, and Intalling Aiki on your Localhost

Next, you'll want to test those changes you've made. To begin:

  • cd aikiframework
  • ./autogen.sh Runs a script that generates a package in the aikiframework/build directory
  • cd build

Next, you'll need to configure the package to run on your specific machine.

Since my installation is using MAMP, I'll need to be sure to specify the correct paths, and this long ugly statement does that:

  • HTTPD_USER=[your_apache_user] HTTPD_CONF_DIR=/Applications/MAMP/conf/apache ../configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --disable-desktop

Next up, is to install the package:

  • Still in the build directory, in Terminal: sudo make install

Create Mysql User & Db

Now that Aiki Framework prepped on your localhost, you need to create mysql user & db to begin testing the software

  • From Terminal, type: make install-mysql-user // provide passwords
  • type: make install-mysql-database

Testing Code

From here, you're free to navigate to http://localhost/aiki & begin testing your updated code!

Uninstalling & removing test data

After you're finished testing, you can uninstall Aiki & the mysql data you created:

  • sudo make uninstall
  • make uninstall-mysql-database
  • make uninstall-mysql-user
  • cd .. you should now be in the aikiframework directory
  • scripts/bone-clean.sh this will clean out the code you generated earlier & get it nice & ready to be committed

Committing Revised & Tested code to Launchpad

Once you're certain of the changes you've made, it's time to commit that code to the Launchpad trunk:

  • From Terminal, type: bzr commit -m "type a short message describing changes you've made"

Congratulations

You're all set up & ready to continue helping push Aiki Framework forward on a Mac!

Example Apache conf file

This file will be installed automatically. 

Alias /aiki /usr/share/aiki

# The following directories require access over HTTP
<Directory /usr/share/aiki/>
    Order Allow,Deny
    Allow from All
    Deny from None
    AllowOverride All
    Options +FollowSymLinks
    RewriteEngine on
    RewriteBase /aiki/
    RewriteRule ^image/(.*)px/(.*)/(.*) assets/apps/image_viewer.php?id=$3&size=$1&mode=$2
    RewriteRule ^image/(.*)px/(.*) assets/apps/image_viewer.php?id=$2&size=$1
    RewriteRule ^image/(.*) assets/apps/image_viewer.php?id=$1
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{SCRIPT_FILENAME} !-d
    RewriteCond %{SCRIPT_FILENAME} !-f
    RewriteRule ^(.*)$ index.php?pretty=$1 [L,QSA]
</Directory>
Retrieved from "http://aikiframework.org/wiki/HOWTO_Develop_Aiki_Framework"
Personal tools