================================================================================
The intended audience for this README is a developer on this project.
================================================================================


- About OSSDiscovery
====================

OSS Discovery finds the open source software embedded in applications and
installed on computers. OSS Discovery helps enterprises better manage open
source usage and remain compliant with internal policies, regulations, and
software license terms.

OSS Discovery, from version 2 on, was built originally to support the
OSS Census efforts in 2007-2008 which was an effort to show how prevalent
Open Source usage was in the world and in enterprises.

- CLI 
======
  - help - to get the basic CLI help, from the project main directory run:
	ruby lib/discovery.rb --help
	
   - first smoke test
	ruby lib/discovery.rb --path ./

    this will dump a list of control-group content found in the development
    tree and give you an indication that discovery is finding packages

- Testing
===========
- Setting up so tests can be run properly:
  - Currently, you must run the following series of commands to set up your 
    environment for testing.  Doing this is only required once/the first time. 
    This has to be done because subversion, by default, wouldn't allow the types 
    of stuff generated by these scripts to be checked in (primarly hidden stuff 
    that starts with a '.').

    TODO findme: replace this current manual step by having the tests that need 
    this stuff set up call out to this script on their own.

    - cd test/resources/content-cg/symlink-tests
    - ./run-me.sh
    - cd -
    - cd test/resources/content-cg/hidden-tests
    - ./run-me.sh
    - cd -
    - ruby test/ts_test_ci.rb
      -> all tests should pass now 
         ('ci' stands for continuous integration, the suite run by the 
          CruiseControl.rb server)

- Creating tests:
  - All test cases (The term 'test' and 'test case' mean the same thing as used 
    in this README.) should conform to the naming standard of 'tc_*.rb'.
  - Make the beginning portion of your test where you specify your 'require' 
    statements match that of an existing test. 
    Specifically, the line of code with 'unshift' in it is performing some load 
    path magic taken directly from the pickaxe book that enables you to run the 
    test from any directory.
  - As long as a newly created test conforms to the naming standard, it will 
    automatically be picked up by the 'ts_test_all.rb' test suite, so you do not 
    have to manually add it to a list of tests to run in any way.
  - Any specific, control-group type test content is found in test/content-cg
    the content-cg includes specific test directory structures (symlinks)
    or specific content versions to test.
  - If you want to write a quick, fairly black box test to verify that something 
    is discoverable, please see the TclongDiscoverItSpeed1 test case and 
    leverage what's being done there.

- Running tests (assuming you're 'pwd' is the project's main directory):
  - 'ruby test/matchrules/tc_match_rule.rb' runs an individual test in match rules
  - 'ruby test/ts_test_all.rb' runs a test suite
    => If all of the test cases do not adhere to the aforementioned naming standard 
       of 'tc_*.rb' then they will not be picked up and run when you run 'ts_test_all.rb'.
  - 'ruby test/matchrules/tc_filename_match_rule.rb --name test_match_true'
    => runs the specific test method named 'test_match_true' in the 'tc_filename_match_rule.rb' test case

	Warning: if you're using TextMate on Mac OS X - the symlink tests directory will
	cause TextMate to drive into oblivion apparently due to it trying to walk the 
	circular sym link directory.  This is exactly the reason why the circular sym link
	directory is in our test suite so it will exercise our walker and make sure the 
	walker algorithms are correct.  Wish TextMate did the same!

- Continuous Integration
  - The command run by the Continuous Integration server:

    ruby ./main/ci/ci.sh 


- Documentation
================
  Use rdoc to generate the code documentation into the doc directory
  From the project root directory, run this command:
    - 'rdoc -o doc lib'

- Configuration
================
  - global configuration file is found in main/lib/conf/config.yml
	  This file contains the user-changeable defaults the application will use.
  - filters
	- discovery pulls in main/lib/filters/filters-list.rb 
	- filters-list.rb pulls in the generic inclusion and exclusion filters
	  To Add a New Filter
	     1) write the filter using an existing example and place the filter .rb file in the filters directory
	     2) Add the require of the filter .rb file to the generic-exclusions.rb file to pull it in.
    - For linux users who would like to not scan anything in their /media directory add the no-media.rb require
      to the generic-exlusions.rb file.  We may add a "no media" flag to the CLI options in the future.


- LEGAL NOTICE
===============

OSS Discovery is a tool that finds installed open source software.

  Copyright (C) 2007-2013 OpenLogic, Inc.

OSS Discovery is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License version 3 as 
published by the Free Software Foundation.  

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License version 3 (LICENSE file) 
for more details.

You should have received a copy of the GNU Affero General Public License along with this program.  
If not, see http://www.gnu.org/licenses/>.

This software contains components licensed under the LGPL.  See NOTICE file for the license terms of the LGPL.

3rd party software included and distributed with OSS Discovery is listed in the NOTICE file.

You can learn more about OSSDiscovery, report bugs and get the latest versions at www.ossdiscovery.org.
You can contact the OSS Discovery team at [email protected].
You can contact OpenLogic at [email protected].