FAQ

Table of Contents

  1. Using This Wiki
    1. How do I edit the wiki?
    2. Attach and show an image on this wiki
    3. Insert code on this wiki
  2. 5 Minute Installation
    1. What's a command prompt?
    2. How do I check out the code?
    3. Why can't I commit code?
    4. Application Requirements
    5. Why do I have to install all this stuff?
  3. 5 Minute "Run The Application"
    1. Project setup (optional)
    2. Run the web app
  4. Development Help
    1. I don't understand the code
    2. Object attributes
    3. Interactive Django
  5. Misc
    1. What is ThoughtAndMemory.org?
    2. ContentType? errors
    3. Sqlite bug

If you have any questions, problems or useful tips let us know. Email dev DASH flock AT mit DOT edu or edit this wiki!

Using This Wiki

How do I edit the wiki?

To edit pages, first register for an account by clicking on "Register" from the top-most menu. After logging in, edit pages using the "Edit this page" button at the bottom of the page.

Attach and show an image on this wiki

The "Attach File" button should appear at the bottom of the page next to "Edit Page". If it does not and you would like to attach a file please email Lucy.

To show the image use WikiMacros (search page for [[Image]]); eg,

[[Image(photo.jpg, 120px)]]

Float the image, eg

[[Image(photo.jpg, 120px, right)]]

Insert code on this wiki

Preformatted (that is, no wiki formatting) text is enclosed in three curly braces. To use WikiProcessors, begin the enclosed text with the magic words: #!html or #!python, etc.

eg, to show html for floating an image 

{{{
#!html
  <div style="float:right;">
    <a href="/trac/attachment/wiki/DesignOverview/sys.jpg">
      <img src="/trac/raw-attachment/wiki/DesignOverview/sys.jpg" />
    </a>
  </div>
}}}

5 Minute Installation

What's a command prompt?

A command prompt is a text based interface for issuing commands. Mac does this via the Terminal application, which is located in Applications/Utilities/Terminal. Windows does this via the Command Prompt (Cmd), which is located in Start->Programs->Accessories->Command Prompt, and can also be opened by going to Start->Run, typing "cmd" and pressing enter.

BILUMI developer are not required to use the command prompt. Some install Eclipse (Ganymede is the current software version; "Eclipse IDE for Java EE Developers" version, which comes with web tools), with the subclipse SVN, PyDev, Web Tools (optional) and Cold Fusion (optional) plugins, and thus never use the command prompt ever. If we're not iterating towards an environment and tool set that make development efficient and enjoyable, what's the point?

Eclipse helpers: * Use run configurations to replace django commands * If you like Emacs: Go to Eclipse->Preferences->General->Key->Key Bindings and set default to Emacs; you can set your own key bindings here, too.

The rest of these instructions are given in terms of terminal commands. Feel free to follow along in Eclipse. There are lots of tutorials online, so if you don't know how to do something try googling it. We are also happy to offer help over email (dev-flock@mit.edu).

How do I check out the code?

SVN repository location:

http://www.thoughtandmemory.org/repo/huginmunin/trunk

Browse the repository on our trac site through the [browser Browse Source] menu button at the top of the page.

Check out code via the command line like this (replace /home/bear/huginmunin_src with your desired destination): 

svn co http://www.thoughtandmemory.org/repo/huginmunin/trunk/web/hm /home/bear/hm_src

If you don't have svn (aka subversion), download it here. For MacOS X, use Martin Ott's zipped dmg instead. Use the latest version, 1.5.

Graphical svn clients:

Short flash video introducing svn.

Why can't I commit code?

Everyone who commits to trunk needs an account. This helps with social interaction and communication; eg, who to talk with about a particular part of the code. If you want an account send us mail: dev DASH flock AT mit DOT edu. No explanation necessary. We'd love to work with you.

Application Requirements

1. Django. Tip of the trunk, though we'll settle on 1.0 once that's out. 

svn co http://code.djangoproject.com/svn/django/trunk django_src

2. python 2.4 or higher. Python is correctly installed when you can open a command prompt, type "python" and have the python evaluator run. The evaluator should also tell you the python version you are running. Type "quit()" or ctrl-d to quit. Helpful python tutorial

  • MacOS X: Python is probably already installed and on your path. If you have the wrong version follow these steps.
  • Windows: After installing python, add the path-to-your-python-exe-file (eg, C:\Python24) to your PATH environment variable. You must open a new command prompt after doing this. To find the environment variable dialog box in Windows go to "Start" -> "My Computer" (or "Computer" in Vista) -> "Properties" -> "Advanced" tab -> "Environment Variables" button. Wikipedia's guide to environment variables.

3. database, eg: sqlite3, mysql or postgres. The simplest database to use is sqlite3. Sqlite3 is correctly installed when you can open a command prompt, type "sqlite3" and have the sqlite3 program run. Type ctrl-d to quit.

  • MacOS X: Sqlite3 is probably already installed and on your path.

4. (optional) firebug, a firefox plugin, that helps with debugging client-side scripts, profiling rendering and investigating CSS, DOM and HTTP posts and responses. There is also an Internet Explorer, Opera and Safari compatible version, firebug lite.

Why do I have to install all this stuff?

Most web applications are comprised of three parts: the client-side browser computations (javascript, flash) and rendering (html, css); the server-side computations (python in our case; languages similar in function include php and ruby); and the data storage (databases such as sqlite3, mysql and postgre).

The bottom database layer is crucial; luckily some database application comes with most operating system distributions (except Windows).

The top HTTP layer is important for seeing the end web app, though not strictly necessary if you're working on python guts. All operating system distributions come with some kind of browser, though, so you don't need to do any work there (though eventually it's good to run multiple browsers and VMs for checking browser/OS support).

Django, written in Python, encompasses the middle layer. It provides useful libraries and abstractions between the bottom database level and the top HTTP level. We've added our own python utilities and API, too. Even if you OS has python, you'll still need to download Django. That wasn't so painful, was it?

5 Minute "Run The Application"

The application, btw, is not all of trunk, but just trunk/web/hm. These instructions assume you're working out of there.

Project setup (optional)

You don't need to mess with local settings.py configuration if you're using sqlite3 and are OK with a default configuration; nonetheless, you might find this interesting.

In order for django to manage the backend, it needs to know where things live. This configuration occurs in the global settings.py file that is located in the root of the project. You checked out this file with the project and do not need to modify it.

You do need to add local configuration information about which database you're using. This means creating a local settings.py file in a sub-directory of env. env contains personal directories, each one containing a settings.py file specific to someone's personal machine.

For example, env/sqlite3_default contains a settings.py file with a default sqlite3 configuration, while env/dan contains a settings file with Dan's mysql and middleware information.

How does Django know which local settings.py file to use? Each project's env directory should contain a text file called CURRENT, which contains a single line of text that is the name of the directory to use for local setttings. CURRENT is not check in since it is specific to each person's setup.

If no env/CURRENT file exists, env/CURRENT.default is used by default, which may or may not work depending on your setup.

To configure your local settings: 1. Create a directory in env with a unique name 2. Create a text file in env called CURRENT which contains only the name of the directory you created in step 1. 3. Create a settings.py file that specifies database and middleware specific information. eg, for mysql: 

DEBUG = True
DEBUG_SQL = True
TEMPLATE_DEBUG = DEBUG

DATABASE_ENGINE = 'mysql'
DATABASE_NAME = 'hm_dev'
DATABASE_USER = 'bilumi'             # Not used with sqlite3.
DATABASE_PASSWORD = 'plaintextpassword!!one!'         # Not used with sqlite3.
DATABASE_HOST = 'set this if your msqld.sock is not in the usual place'             # Set to empty string for localhost. Not used with sqlite3.
DATABASE_PORT = ''             # Set to empty string for default. Not used with sqlite3.

MIDDLEWARE_CLASSES += (
    'lib.sql_log_middleware.SQLLogMiddleware',
    'lib.visit_log_middleware.LogVisits',
)

Run the web app

From the project root (same level as the global settings.py file):

0. Optional: Setup a database with test data

Run the load_small_dev_db.sh script in trunk/web/hm/db/fixtures/small_dev from a command prompt: 

./db/fixtures/small_dev/load_small_dev_db.sh

Or use Django's manage.py script to reset, dump and load data. 

./manage.py help

1. Run the django dev server 

./manage.py runserver

2. Use the web app

Open a web browser and enter http://localhost:8000/Main (or the host and port number entered with runserver).

Development Help

I don't understand the code

The main page of this wiki contains link to wiki documentation and the python APIs. We're working to improve our internal frameworks, and will eventually have docs to support them (eg, dealing with forms (templatetag, view)), so let us know if you're having trouble with anything in particular.

Object attributes

If you're new to python checkout

  • help(object)
  • dir(object)

Help displays the docsrings, and dir prints all the attributes (eg, fields, methods). This information is also available through the epydoc APIs:

Interactive Django

Run the code below in a python interpreter to be able to do things like 

    n = Node.objects.get(id=3)

Putting this code in a file, called say interactive.py, will you to start the python interpreter and then do 'import interactive' 

# your TAM project (director containing TAM's settings.py file)
database_settings = '/var/sites/hm_www'
        
# set up Django environment
sys.path.append(database_settings)
DJANGO_SETTINGS_MODULE=database_settings
from django.core.management import setup_environ
import settings
setup_environ(settings)
from django.db.models import *

# set up ThoughtAndMemory application environment
from db.models import *
from db.graph import *

A guide to setting up an interactive django shell in Eclipse.

Misc

What is ThoughtAndMemory.org?

Please see the blog pages for more information about ThoughtAndMemory.org

ContentType? errors

solution

Sqlite bug

Result of select query changes after adding an index

This bug is fixed in the sqlite source code, but the binaries on their website and (probably) on your computer are older and do not contain the fix.

To get the fixed version of sqlite you will need to checkout the code from the repository, configure it, make it and install it. Enter the following commands in order:

*command* *description*
cd ~/Projects change directory (cd) to wherever you want to put the sqlite source
cvs -d :pserver:anonymous@www.sqlite.org:/sqlite login add login information for sqlite repository to ~/.cvspass
anonymous password for repository
cvs -d :pserver:anonymous@www.sqlite.org:/sqlite checkout -d sqlite_src sqlite checkout sqlite module from repository into sqlite_src directory on your computer
cat sqlite/README read the install instructions to promote good habits
mkdir sqlite_build separate the build from the source
cd sqlite_build cd to build directory
../sqlite_src/configure create configuration files in the build directory using the source directory
make compile
make install install. optional, but will put things in the right place

On Macs, sqlite3 is already installed in /usr/bin/sqlite3 

which sqlite3
% /usr/bin/sqlite3

If you need more help, eg with path issues, let us know.