git.oblomov.eu Git - ohcount/blob - README

   1 = Ohcount
   2
   3 The Ohloh source code line counter
   4
   5 This program is free software; you can redistribute it and/or modify
   6 it under the terms of the GNU General Public License Version 2 as
   7 published by the Free Software Foundation.
   8
   9 Ohcount is specifically licensed under GPL v2.0, and no later version.
  10
  11 This program is distributed in the hope that it will be useful,
  12 but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 GNU General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with this program; if not, write to the Free Software
  18 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  19
  20 == Overview
  21
  22 Ohcount is a library for counting lines of source code.
  23 It was originally developed at Ohloh, and is used to generate
  24 the reports at www.ohloh.net.
  25
  26 Ohcount supports multiple languages within a single file: for example,
  27 a complex HTML document might include regions of both CSS and JavaScript.
  28
  29 Ohcount has two main components: a detector which determines the primary
  30 language family used by a particular source file, and a parser which
  31 provides a line-by-line breakdown of the contents of a source file.
  32
  33 Ohcount includes a command line tool that allows you to count individual
  34 files or whole directory trees. It also allows you to find source code
  35 files by language family, or to create a detailed annotation of an
  36 individual source file.
  37
  38 Ohcount includes a Ruby binding which allows you to directly access its
  39 language detection features from a Ruby application.
  40
  41 == System Requirements
  42
  43 Ohcount is supported on Mac OS X 10.4 and Ubuntu 6.06 LTS. Other Linux
  44 environments should also work, but your mileage may vary.
  45
  46 Ohcount does not support Windows.
  47
  48 Ohcount targets Ruby 1.8.6. The build script targets Rake 0.7.3. You will
  49 also require a C compiler to build the native extensions.
  50
  51 Ohcount requires the pcre library (http:///www.pcre.org).
  52
  53 == Download
  54
  55 The source code for ohcount is available as a tarball:
  56
  57   http://labs.ohloh.net/download/ohcount-1.0.0.tgz
  58
  59 You can also download the source code as a Git repository:
  60
  61   git clone http://git.ohloh.net/git/ohcount.git
  62
  63 == Installation
  64
  65 Ohcount is packaged as a RubyGem. To build and install the gem (you will need
  66 root priveleges for the install):
  67
  68   $ rake install
  69
  70 To uninstall the RubyGem:
  71
  72   $ gem uninstall ohcount
  73
  74 If you do not want to install the gem, you can simply build and run it like this:
  75
  76   $ rake
  77   $ bin/ohcount
  78
  79 == First Steps
  80
  81 To measure the lines of code, simply pass filenames or directory names
  82 to the +ohcount+ script:
  83
  84   $ ohcount helloworld.c
  85
  86 Directories will be probed recursively. If you do not pass any parameters,
  87 the current directory tree will be counted.
  88
  89 You can use the ohcount +detect+ option to simply determine the language
  90 family of each source file. The files will not be parsed or counted.
  91 For example, to find all of the ruby files in the current directory tree:
  92
  93   $ ohcount --detect | grep ^ruby
  94
  95 The +annotate+ option presents a line-by-line accounting
  96 of the languages used in a source code file. For example:
  97
  98   $ ohcount --annotate ./test/src_dir/php1.php
  99
 100 == Loading ohcount from Ruby
 101
 102 If you have installed ohcount as a gem, you can load it like this:
 103
 104   require 'rubygems'
 105   require 'ohcount'
 106
 107 If you have not installed the gem, you'll have to make sure that
 108 ohcount is on your ruby load path and then require:
 109
 110   require 'ohcount'
 111
 112 The <tt>bin/ohcount</tt> script shows examples of calling the ohcount
 113 libraries from Ruby.
 114
 115 == How to Add a New Language
 116
 117 These are the steps required to add a new language to ohcount:
 118
 119 * Update Ohcount::Detector to identify files that use the new language.
 120 * Update Ohcount::DetectorTest to confirm the Detector changes.
 121 * In Ohcount::Generator, instantiate a new Ohcount::Monoglot or
 122   Ohcount::Polyglot to parse the language.
 123 * Create a new Ohcount::Test to verify the parser.
 124
 125 == Contact Ohloh
 126
 127 For more information visit the Ohloh website:
 128    http://labs.ohloh.net
 129
 130 You can reach Ohloh via email at:
 131    info@ohloh.net