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, see <http://www.gnu.org/licenses/>.
  18
  19 == Overview
  20
  21 Ohcount is a library for counting lines of source code.
  22 It was originally developed at Ohloh, and is used to generate
  23 the reports at www.ohloh.net.
  24
  25 Ohcount supports multiple languages within a single file: for example,
  26 a complex HTML document might include regions of both CSS and JavaScript.
  27
  28 Ohcount has two main components: a detector which determines the primary
  29 language family used by a particular source file, and a parser which
  30 provides a line-by-line breakdown of the contents of a source file.
  31
  32 Ohcount includes a command line tool that allows you to count individual
  33 files or whole directory trees. It also allows you to find source code
  34 files by language family, or to create a detailed annotation of an
  35 individual source file.
  36
  37 Ohcount includes a Ruby binding which allows you to directly access its
  38 language detection features from a Ruby application.
  39
  40 == System Requirements
  41
  42 Ohcount is supported on Mac OS X 10.5 and Ubuntu 6.06 LTS. Other Linux
  43 environments should also work, but your mileage may vary.
  44
  45 Ohcount does not support Windows.
  46
  47 Ohcount targets Ruby 1.8.6. The build script targets Rake 0.8.1. You will
  48 also require a C compiler to build the native extensions.
  49
  50 == Download
  51
  52 Ohcount source code is available as a Git repository:
  53
  54   git clone http://git.ohloh.net/git/ohcount.git
  55
  56 == Building Ohcount
  57
  58 During the build process, Ohcount requires Ragel version 6.3 or later.
  59 Older versions of Ragel are not compatible. Visit the Ragel homepage at:
  60
  61   http://research.cs.queensu.ca/~thurston/ragel/
  62
  63 Once Rake, GCC, and Ragel 6.3 are installed, you can build Ohcount as follows:
  64
  65   $ rake
  66
  67 Ohcount can optionally be installed as a RubyGem. To build and install the gem
  68 (you will need root priveleges for the gem install):
  69
  70   $ rake gem
  71   $ gem install pkg/ohcount-2.0.0
  72
  73 To uninstall the RubyGem:
  74
  75   $ gem uninstall ohcount
  76
  77 == First Steps
  78
  79 To measure lines of code, simply pass file or directory names to the +ohcount+
  80 script, located in the +bin+ subdirectory:
  81
  82   $ ohcount helloworld.c
  83
  84 Directories will be probed recursively. If you do not pass any parameters,
  85 the current directory tree will be counted.
  86
  87 You can use the ohcount +detect+ option to simply determine the language
  88 family of each source file. The files will not be parsed or counted.
  89 For example, to find all of the ruby files in the current directory tree:
  90
  91   $ ohcount --detect | grep ^ruby
  92
  93 The +annotate+ option presents a line-by-line accounting
  94 of the languages used in a source code file. For example:
  95
  96   $ ohcount --annotate ./test/src_dir/php1.php
  97
  98 == Loading Ohcount From Ruby
  99
 100 If you have not installed the gem, you'll have to make sure that
 101 ohcount is on your Ruby load path and then require:
 102
 103   require 'ohcount'
 104
 105 If you have installed ohcount as a gem, you can load it like this:
 106
 107   require 'rubygems'
 108   require 'ohcount'
 109
 110 The <tt>bin/ohcount</tt> script shows examples of calling the ohcount
 111 libraries from Ruby.
 112
 113 == How to Add a New Language
 114
 115 These are the steps required to add a new language to ohcount:
 116
 117 * Update Ohcount::Detector to identify files that use the new language.
 118 * Update Ohcount::DetectorTest to confirm the Detector changes.
 119 * Follow the detailed instructions in PARSER_DOC.
 120 * In Ohcount::Language, provide a "nice name" and category (procedural
 121   code vs. markup) for the new language.
 122 * Create a new Ohcount::Test to verify the parser.
 123
 124 == Contact Ohloh
 125
 126 For more information visit the Ohloh website:
 127    http://labs.ohloh.net
 128
 129 You can reach Ohloh via email at:
 130    info@ohloh.net