Difference between revisions of "Directory Structure"

From Dreamwidth Notes
Jump to: navigation, search
(Clarified/extended cgi-bin/ definition)
(→‎etc)
 
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
[[Category: Development]]
 
[[Category: Development]]
 +
This documents the contents of the $LJHOME development folder as present on all Dreamhacks.
  
−
This documents the development folder checked out by <code>bootstrap.pl</code>.
+
= bin =
  
−
=Directories you will use a lot=
+
Backend utilities for maintaining and upgrading the site.
  
−
== [[Main development folder/bin|bin]] ==
+
Commonly used programs in this directory include:
 +
* [[Script: checkconfig.pl|checkconfig.pl]]
  
−
This directory contains backend utilities for maintaining and upgrading the site.
+
Subdirectories are:
 +
==dev==
 +
==maint==
 +
==misc==
 +
==upgrading==
  
−
== [[Main development folder/cgi-bin|cgi-bin]] ==
+
= cgi-bin =
  
−
This directory contains the code that runs the site.  This is the base of the library path--that is <code>use Net::OpenID::Consumer;</code> refers to the code in <code>cgi-bin/Net/OpenID/Consumer.pm</code>. It contains all the custom Perl libraries functions that the code references, including the <code>LJ::*</code> and <code>DW::*</code> libraries.
+
Code libraries that power the site.  This directory is the base of the library path--that is <code>use Net::OpenID::Consumer;</code> refers to the code in <code>cgi-bin/Net/OpenID/Consumer.pm</code>. It contains all the custom Perl libraries and functions that the code references including the <code>LJ::*</code> and <code>DW::*</code> libraries.
  
−
== [[Main development folder/htdocs|htdocs]] ==
+
All subdirectories here map to library names, so <code>DW::Foo</code> goes in <code>cgi-bin/DW/Foo.pm</code> and so forth.
  
−
This directory contains most of the user-facing pages, with the directory structure used on the main website. That is to say, anything that appears at <code>http://www.dreamwidth.org/filename.bml</code> will be here, as <code>htdocs/filename.bml</code>; anything at <code>http://www.dreamwidth.org/directory/filename.bml</code> will be here as <code>htdocs/directory/filename.bml</code>, etc. To see your changes on your development site, you need to make the changes to the appropriate file in this directory.
+
Code in <code>*.pl</code> files in this directory are also library files but in an older style that haven't been converted over to use .pm. These are described in [[Legacy .pl Files]].
  
−
== [[Main development folder/ssldocs|ssldocs]] ==
 
  
−
This contains pages that are transmitted over SSL instead of being unencrypted. Regular files live in <code>htdocs</code>.
+
== LJ ==
  
−
== [[Main development folder/views|views]] ==
+
Original LJ modules.
  
−
This contains [[Template Toolkit]] files, as part of our conversion from BML to Template Toolkit.  The controllers for the templates are in <tt>cgi-bin/DW/Controller/</tt>.
+
== DW ==
  
−
=Special directory=
+
Newer, DW-based modules.
  
−
== [[Main development folder/cvs|cvs]] ==
+
= doc =
  
−
The cvs folder contains a local checkout of the [http://hg.dwscoalition.org Mercurial repositories]. To generate a patch for your changes that can be applied, you need to make the changes to the appropriate changes in this directory, <em>after</em> you have verified that the changes work, testing them by putting them in <code>htdocs</code>, <code>cgi-bin</code>, or <code>ssldocs</code> and viewing them (and testing them) on your development site. Once you've done that, you can use the automatic tools to sync your "live" directories and your cvs directory. More information can be found at [[http://wiki.dwscoalition.org/notes/Dev_Initial_Programming_Notes]].  
+
Unedited versions of some configuration files are stored here, plus the DocBook manual.
  
−
The two Mercurial source branches you'll be using most often are <code>dw-free</code> [http://hg.dwscoalition.org/dw-free/ dw-free] and <code>dw-nonfree</code> [http://hg.dwscoalition.org/dw-nonfree/ dw-nonfree]. (When viewing the Mercurial page for each repo, the 'Manifest' link in the top menu bar will allow you to browse the source tree.)
+
== raw ==
  
 +
Docbook formatted source for the old and very much out of date docbook code for the LiveJournal server. LiveJournal's version is visible at <code>http://livejournal.com/doc/server/</code> but Dreamwidth has not generated a user-visible copy.
  
−
=Directories you will not need to change often=
+
= etc =
  
−
These are directories you won't need to change often, unless you're working on some specific task related to them.
+
Various configuration files such as [https://github.com/dreamwidth/dw-free/blob/develop/etc/config.pl <code>config.pl</code>]. These serve as examples of a prototypical site only; actual running sites should set up local config files in ext/local.  
  
−
== doc ==
+
To add new items to be configured, see cgi-bin/LJ/Global/Defaults.pm
  
−
Most notable thing in here is the docbook code for the server and LJ programming guides.
+
= ext =
  
−
== etc ==
+
This directory contains any local repository checkouts--for instance, <tt>dw-nonfree</tt>, Dreamwidth's non-open source code, goes here. The directory structure in <tt>dw-nonfree</tt> is parallel to the root directory structure -- that is, it contains folders such as htdocs, cgi-bin, bin, though not all folders are present.
  
−
Empty in a clean checkup.  Your site's <code>ljconfig.pl</code> will go here, to make sure the original <code>ljconfig.pl</code> can be updated without ill effects on a running installation.
+
This directory also contains [[Dreamwidth_Scratch_Installation#Editing_the_config_files|local config files]] in <tt>ext/local/etc</tt>, so they won't be affected by source code updates.
  
−
== logs ==
+
= htdocs =
  
−
Looks to be an empty folder to store logs during running the code.
+
User-facing [[BML]] pages, with the directory structure used on the main website. That is to say, anything that appears at <code>http://www.dreamwidth.org/filename.bml</code> will be here, as <code>htdocs/filename.bml</code>; anything at <code>http://www.dreamwidth.org/directory/filename.bml</code> will be here as <code>htdocs/directory/filename.bml</code>, etc.
  
−
== [[Main development folder/src|src]] ==
+
We are in the process of translating these files into controllers, found in <code>cgi-bin/DW/Controller/</code>, and templates, found in <code>views</code>.
  
−
Confusingly enough, contains source for some of the packages the code uses.  Perhaps this is the folder that comes with the distribution and <code>cvs</code> is checked out from the other repositories?  Does not contain all of the ones in <code>cvs</code> though.
+
==js==
  
−
== [[Main development folder/t|t]] ==
+
JavaScript files. Files not under the folders listed below are considered legacy and are only around because they're being used on older (unconverted) pages. They shouldn't be touched to add new features, only to fix (critical) bugs.
  
−
Looks like this contains the tests that use the testing framework in main/test.  See [[Dev Testing]] for how to use them.
+
===components===
 +
Reusable components that can be used across pages
  
−
== temp ==
+
===foundation===
 +
The Foundation library files. Don't touch.
  
−
Empty in a clean install. Probably used for temporary file storage.
+
===jquery===
 +
The jQuery library files. Don't touch.
  
−
== test ==
+
===pages===
 +
Per-page JS files. Directory structure should match that of views/ below. Try to keep to a minimum: should mostly be initialization of reusable components.
  
−
Very sparse directory; really not much here.
+
==stc==
 +
Older CSS files. To be converted to SCSS.
  
−
== var ==
+
==scss==
  
−
A clean install of this only includes devdata/evillaugh.wav.  Nobody remembers what this is for.
+
===components===
 +
Styling for reusable components that can be used across pages.
 +
 
 +
===foundation===
 +
The Foundation library files. As much as possible, don't touch. Try to make any changes to components/foundation-custom/*, to make it easier to upgrade if needed.
 +
 
 +
===mixins===
 +
SCSS mixins that are meant to be included into other SCSS files as needed.
 +
 
 +
===pages===
 +
Per-page SCSS files. Directory structure should match that of views/ below. Try to keep per-page styling to a minimum, and instead use Foundation classes in your HTML when possible.
 +
 
 +
===skins===
 +
SCSS files for site skins. Contains actual skins as well as files that are included for all skins. Any color settings should only be in this folder.
 +
 
 +
= logs =
 +
 
 +
Some of the Dreamwidth sub-systems keep log files here, including the journal importer.
 +
 
 +
= schemes =
 +
 
 +
[[Template Toolkit]] (<code>*.tt</code>) files for generating the site schemes used on Dreamwidth.
 +
 
 +
= src =
 +
 
 +
Source code for some of the third-party packages the code uses.
 +
 
 +
= t =
 +
 
 +
Tests that use the testing framework in main/test.  See [[Dev Testing]] for how to use them.
 +
 
 +
= temp =
 +
 
 +
Used by the doc system (ljconfig2db.pl). Which means basically unused right now.
 +
 
 +
= views =
 +
 
 +
[[Template Toolkit]] files which are gradually replacing the BML files.  The controllers for the templates are in <tt>cgi-bin/DW/Controller/</tt>.
 +
 
 +
==components==
 +
Reusable components. See the [http://www.dreamwidth.org/dev/style-guide the style guide] for examples of how to call them.

Latest revision as of 00:27, 8 November 2015

This documents the contents of the $LJHOME development folder as present on all Dreamhacks.

bin

Backend utilities for maintaining and upgrading the site.

Commonly used programs in this directory include:

Subdirectories are:

dev

maint

misc

upgrading

cgi-bin

Code libraries that power the site. This directory is the base of the library path--that is use Net::OpenID::Consumer; refers to the code in cgi-bin/Net/OpenID/Consumer.pm. It contains all the custom Perl libraries and functions that the code references including the LJ::* and DW::* libraries.

All subdirectories here map to library names, so DW::Foo goes in cgi-bin/DW/Foo.pm and so forth.

Code in *.pl files in this directory are also library files but in an older style that haven't been converted over to use .pm. These are described in Legacy .pl Files.


LJ

Original LJ modules.

DW

Newer, DW-based modules.

doc

Unedited versions of some configuration files are stored here, plus the DocBook manual.

raw

Docbook formatted source for the old and very much out of date docbook code for the LiveJournal server. LiveJournal's version is visible at http://livejournal.com/doc/server/ but Dreamwidth has not generated a user-visible copy.

etc

Various configuration files such as config.pl. These serve as examples of a prototypical site only; actual running sites should set up local config files in ext/local.

To add new items to be configured, see cgi-bin/LJ/Global/Defaults.pm

ext

This directory contains any local repository checkouts--for instance, dw-nonfree, Dreamwidth's non-open source code, goes here. The directory structure in dw-nonfree is parallel to the root directory structure -- that is, it contains folders such as htdocs, cgi-bin, bin, though not all folders are present.

This directory also contains local config files in ext/local/etc, so they won't be affected by source code updates.

htdocs

User-facing BML pages, with the directory structure used on the main website. That is to say, anything that appears at http://www.dreamwidth.org/filename.bml will be here, as htdocs/filename.bml; anything at http://www.dreamwidth.org/directory/filename.bml will be here as htdocs/directory/filename.bml, etc.

We are in the process of translating these files into controllers, found in cgi-bin/DW/Controller/, and templates, found in views.

js

JavaScript files. Files not under the folders listed below are considered legacy and are only around because they're being used on older (unconverted) pages. They shouldn't be touched to add new features, only to fix (critical) bugs.

components

Reusable components that can be used across pages

foundation

The Foundation library files. Don't touch.

jquery

The jQuery library files. Don't touch.

pages

Per-page JS files. Directory structure should match that of views/ below. Try to keep to a minimum: should mostly be initialization of reusable components.

stc

Older CSS files. To be converted to SCSS.

scss

components

Styling for reusable components that can be used across pages.

foundation

The Foundation library files. As much as possible, don't touch. Try to make any changes to components/foundation-custom/*, to make it easier to upgrade if needed.

mixins

SCSS mixins that are meant to be included into other SCSS files as needed.

pages

Per-page SCSS files. Directory structure should match that of views/ below. Try to keep per-page styling to a minimum, and instead use Foundation classes in your HTML when possible.

skins

SCSS files for site skins. Contains actual skins as well as files that are included for all skins. Any color settings should only be in this folder.

logs

Some of the Dreamwidth sub-systems keep log files here, including the journal importer.

schemes

Template Toolkit (*.tt) files for generating the site schemes used on Dreamwidth.

src

Source code for some of the third-party packages the code uses.

t

Tests that use the testing framework in main/test. See Dev Testing for how to use them.

temp

Used by the doc system (ljconfig2db.pl). Which means basically unused right now.

views

Template Toolkit files which are gradually replacing the BML files. The controllers for the templates are in cgi-bin/DW/Controller/.

components

Reusable components. See the the style guide for examples of how to call them.

Retrieved from "http://wiki.dreamwidth.net/wiki/index.php?title=Directory_Structure&oldid=12503"