================================================================================ 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 firstname.lastname@example.org. You can contact OpenLogic at email@example.com.