csd 0.2.2 → 0.3.0

data/.gitignore

@@ -24,4 +24,4 @@ pkg
 
 ## PROJECT::SPECIFIC
 drop
-edge
+edge

data/README.rdoc

@@ -2,12 +2,24 @@
 
 CSD stands for Communication Systems Design and is a project of the Telecommunication Systems Laboratory (TSLab) of the Royal Institute of Technology in Stockholm, Sweden. Within CSD many software tools are used to build up various networks and services. This gem is supposed to automate processes to handle the compilation and installation of these software tools. Technology Transfer Alliance (TTA) is the project team, which maintains this code.
 
+== Where is it?
+
+* {Installation instructions}[http://ttai.notlong.com/]
+* {Source Code}[http://github.com/csd/csd]
+* {RDoc API}[http://rdoc.info/github/csd/csd/master]
+* {Developer Forks}[http://github.com/csd/csd/network]
+* {Bug Tracker}[http://github.com/csd/csd/issues]
+* {Wiki}[http://wiki.github.com/csd/csd]
+
 == Requirements
 
-* Ruby >= 1.8.7
+* {Ruby}[http://ruby-lang.org] (>= 1.8.7)
+* {RubyGems}[http://rubygems.org] (>= 1.3.7)
 
 == Installation
 
+After having installed RubyGems, in a console, type
+
   (sudo) gem install csd
 
 == Usage
@@ -16,13 +28,14 @@ In a console, type
 
   ai
 
+For more details we refer to the {Wiki}[http://wiki.github.com/csd/csd].
+
 == Note on Patches/Pull Requests
 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so we don't break it in a future version unintentionally.
-* Commit, do not mess with Rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself we can ignore when I pull)
+* Fork the project
+* Make your feature addition or bug fix
+* Add tests for it. This is important so we don't break it in a future version unintentionally
+* Commit, without the Rakefile and the VERSION file
 * Send us a pull request.
 
 == Copyright

data/VERSION

@@ -1 +1 @@
-0.2.2
+0.3.0

data/lib/csd.rb

@@ -10,61 +10,83 @@ Dir[File.join(File.dirname(__FILE__), 'csd', '*.rb')].sort.each { |path| require
 module CSD
   class << self
   
-    # This String holds the name of the executable the user used to bootstrap this gem
+    # This String holds the name of the executable the user used to execute/bootstrap this gem.
+    # It is useful for showing example commands to the end-user, such as "Please type: ai install minisip".
+    # Because the name of the executable might change after some time. Currently, +ai+ and +ttai+ are
+    # supported executables.
     attr_reader :executable
   
     # This method "runs" the whole CSD gem, so to speak.
     #
+    # ==== Options
+    #
+    # The following options can be passed as a hash.
+    #
+    # [+:executable+] A String which holds the name of the exectuable that was used to call this method (default: <tt>[EXECUTABLE]</tt>).
+    #
     def bootstrap(options={})
-      @executable = options[:executable]
+      # Storing the important options into instance variables
+      @executable = options[:executable] || '[EXECUTABLE]'
+      # Reading the command-line arguments
       Options.parse!
+      # Intercepting and processing AI-internal commands such as "ai update" and "ai edge"
       respond_to_internal_ai_options
+      # Ensure that the chosen action, application (and optionally the scope) are valid
       respond_to_incomplete_arguments
       UI.debug "#{self}.bootstrap initializes the task #{Options.action.to_s.enquote if Options.action} of the application #{Applications.current.name.to_s.enquote if Applications.current} now"
+      # Passing on the desired action to the instance of the chosen application module (e.g. passing on "install" to the "MiniSIP" module)
       Applications.current.instance.send("#{Options.action}".to_sym) if Applications.current
     end
   
     private
     
+    # This method is the first in the chain of processing the command-line arguments. It will react to
+    # AI-internal commands such as "update" or "edge".
+    #
     def respond_to_internal_ai_options
-      if !Applications.current and ARGV.include?('update')
+      # If an application was chosen, this is clearly not an internal AI functionality which the user requested
+      return if Applications.current
+      # Other than that, react to some predefined commands
+      if ARGV.include?('update')
         update_ai_using_rubygems
-      elsif !Applications.current and ARGV.include?('edge')
+      elsif ARGV.include?('edge')
         update_ai_to_cutting_edge
       end
     end
     
-    # Updating the AI
+    # Updating the AI via the internal RubyGems mechanism (i.e. <tt>gem update</tt>).
+    # The AI will quit with status code 0 after the operation was successful.
     #
     def update_ai_using_rubygems
       UI.info "Updating the AI to the newest version".green.bold
       Cmd.run "sudo gem update csd --no-ri --no-rdoc", :announce_pwd => false, :verbose => true
-      exit!
+      exit! # with status code 0
     end
     
     # This method is used to conveniently update the AI without officially publishing it on RubyGems.
-    # This can be handy when testing many things on many machines at the same time :)
+    # This can be handy when testing many things on many machines in a very short amount of time :)
+    # Basically this function will download a list of predefined locations on where the cutting-edge
+    # gem of the AI can be obtained from. Then it will go through each location in order to download
+    # and install the edge version. The AI quits after the first successful download+installation attempt.
     #
     def update_ai_to_cutting_edge
       UI.info "Updating the AI to the cutting-edge experimental version".green.bold
       # Create a temporary working directory
       Path.edge_tmp = Dir.mktmpdir
       Path.edge_file = File.join(Path.edge_tmp, 'edge.gem')
-      # Retrieve list of possible locations for edge versions
-      # Note that you can just modify that list to add your own locations
-      # You can modify the list at http://github.com/csd/csd/downloads
-      # Note that the Amazon G3 cache used by Github takes about 12 hours to refresh the file, though!
+      # Retrieve list of possible locations for edge versions. Note that you can just modify that list to add your own locations
+      # You can modify the list at http://github.com/csd/csd/downloads but note that the Amazon G3 cache (used by Github) takes about 12 hours to refresh the file, though!
       for location in Net::HTTP.get_response(URI.parse('http://cloud.github.com/downloads/csd/csd/edge.txt')).body.split.each do
         # See if there is a downloadable edge version at this location. If not, move on to the next location
         next unless Cmd.download(location, Path.edge_file).success?
-        # If the download was successful here, let's update the AI from that downloaded gem-file and exit
+        # If the download was successful here, let's update the AI from that downloaded gem-file and quit the loop
         updated = Cmd.run("sudo gem install #{Path.edge_file} --no-ri --no-rdoc", :announce_pwd => false, :verbose => true).success?
         break
       end
       UI.info "Currently there is no edge version published.".green.bold unless updated
       # Cleaning up the temporary directory
       FileUtils.rm_r Path.edge_tmp
-      exit!
+      exit! # with status code 0
     end
     
     # This method check the arguments the user has provided and terminates the AI with
@@ -72,11 +94,11 @@ module CSD
     #
     def respond_to_incomplete_arguments
       choose_application unless Applications.current
-      choose_action unless Options.valid_action?
-      choose_scope if Options.scope and not Options.valid_scope?
+      choose_action      unless Options.valid_action?
+      choose_scope       if Options.scope and not Options.valid_scope?
     end
   
-    # This methods lists all available applications
+    # This methods lists all applications that the AI currently supports.
     #
     def choose_application
       UI.separator
@@ -95,7 +117,7 @@ module CSD
       raise Error::Argument::NoApplication
     end
 
-    # This methods lists all available actions for a specific application
+    # This methods lists all available actions for the currently selected application.
     #
     def choose_action
       UI.separator
@@ -118,7 +140,7 @@ module CSD
       raise Error::Argument::NoAction
     end
     
-    # This methods lists all available scopes for a specific application and action
+    # This methods lists all available scopes for the currently selected application and action.
     #
     def choose_scope
       UI.separator

data/lib/csd/application.rb

@@ -1,3 +1,2 @@
 # -*- encoding: UTF-8 -*-
-require "csd/application/default"
-
+require "csd/application/default"

data/lib/csd/application/decklink/about.yml

@@ -1,5 +1,5 @@
 human: DeckLink
-description: Capture card drivers for the Blackmagic Design DeckLink device used by MiniSIP.
+description: Blackmagic Design DeckLink capture card drivers.
 actions:
   public:
     - install: Download and install the DeckLink drivers.

data/lib/csd/application/decklink/base.rb

@@ -26,6 +26,7 @@ module CSD
           apply
           add_boot_loader
           send_notification
+          cleanup_working_directory
         end
         
         def introduction

data/lib/csd/application/decklink/options/{install.rb → common.rb}

@@ -2,12 +2,10 @@
 
 opts.headline 'WORKING DIRECTORY OPTIONS'.green.bold
 
-self.temp = true
 opts.on("--no-temp", "Use a subdirectory in the current directory as working directory and not /tmp.") do |value|
   self.temp = value
 end
 
-self.work_dir = nil
 opts.on("--work-dir [PATH]", "Defines and/or creates the working directory. This will override the --no-temp option.") do |value|
   self.work_dir = value
 end

data/lib/csd/application/decklink/options/common_defaults.rb

@@ -0,0 +1,2 @@
+self.temp = true
+self.work_dir = nil

data/lib/csd/application/default.rb

@@ -3,11 +3,16 @@ require 'csd/application/default/base'
 require 'yaml'
 
 module CSD
-  # This namespace holds all individual application Modules
+  # This namespace holds all individual application Modules.
   #
   module Application
   
-    # This is the root class of all Applications
+    # This is a module which contains all methods that each Application must implement. It provides
+    # the basic functionality so that it can be simply included by a real Application module to get
+    # started. The only thing that (in that case) really needs to be implemented is the +instance+
+    # method which chooses and holds the actual Application Module instance which will perform the
+    # task. All other functions in this module just require an +about.yml+ file to be placed in the
+    # specific application sub-directory.
     #
     module Default
       
@@ -18,22 +23,73 @@ module CSD
         raise Error::Application::NoInstanceMethod, "The application module must define an method called `instance´."
       end
       
+      # This method returns the Name of the application formatted as a command-line argument. By default
+      # it returns the name of the own class without capital letters. E.g. the class +MyClass+ would turn
+      # into +my_class+. It can be overwritten by the implementation of the actual application if another
+      # name is desired, or if the name needs to change in the future for some reason.
+      #
       def name
         self.to_s.demodulize.underscorize
       end
-    
+      
+      # This method returns a short description of the application. By default it just reads the description
+      # provided in the +about.yml+ file. It can be overwritten if the +about.yml+ file is not used for some reason.
+      #
       def description
         about.description
       end
-    
+      
+      # In order to present the name of this application to humans, neither the class name, nor the name
+      # as it appears in a command-line argument should be used. In other words, it should not be +Minisip+
+      # or +minisip+, but +MiniSIP+. This method returns that string and it is manually defined in the
+      # +about.yml+ file.
+      #
       def human
         about.human
       end
-    
+      
+      # This method returns a hash containing all valid actions (i.e. tasks) for this application. Note that
+      # the structure of this hash must be in a particular way. In the first level of the hash, a differentiation
+      # is made between actions intended for public use, such as "install" and for AI-developer use, such as
+      # "compile" or "package". For example:
+      #
+      #  {'public' => [...], 'developer' => [...]}
+      #
+      # Each of these two keys holds an +Array+ with the actions. Each action is defined as a hash with the key
+      # as the action name and the value as the action description. One action looks like this for example:
+      #
+      #  [{'install' => 'Downloads and installs the cooles application of all'}]
+      #
+      # Several actions look like this, respectively:
+      #
+      #   [ {'install' => 'Downloads and installs the cooles application of all'},
+      #     {'update'  => 'Updates this cool application fully automatically'}      ]
+      #
+      # The reason for choosing an Array and not a Hash to hold the actions is, because when they are presented
+      # to the end-user, the order of listing them up should be definable. It is not alphabetically, but sorted
+      # manually. A fully valid return value might look like this:
+      #
+      #  { 'public'    => [ {'install' => 'Downloads and installs this application'  }
+      #                     {'remove'  => 'Removes this cool application immediately'} ],
+      #    'developer' => [ {'package' => 'Creates a debian-package for this application'} ]
+      #  }
+      #
       def actions
         about.actions
       end
-    
+      
+      # Some applications might react not only to tasks (such as +install+ or +compile+), but also to a more
+      # fine-grained scope. Typically this is a sub-component of an application. For example, MiniSIP has the
+      # sub-components "FFmpeg", "HDVIPER", "Plugins", etc. If an AI-developer wants to test only a particular
+      # part of the whole installation routine, he can instruct the AI to only perform the tasks needed to
+      # install that sub-component. This will save a lot of time in testing the functionality. In general,
+      # scopes are optional, but they may be defined here.
+      #
+      # The scopes are specific for each action. It might be that the "install" action of minisip, has scopes
+      # a, b, and c, whereas the "compile" action has maybe no scope at all. Similarly to the +actions+ method,
+      # this method defines scopes in a hash, where each key represents one action and the value holds an +Array+
+      # of all available scopes.
+      #
       def scopes(action)
         (about.scopes.is_a?(Hash) and about.scopes.key?(action)) ? about.scopes[action] : []
       end

data/lib/csd/application/graphics.rb

@@ -0,0 +1,30 @@
+# -*- encoding: UTF-8 -*-
+require 'csd/application/default'
+require 'csd/application/graphics/error'
+require 'csd/application/graphics/base'
+
+module CSD
+  module Application
+    # This is the Application Module to update the graphics card drivers.
+    #
+    module Graphics
+      class << self
+
+        include CSD::Application::Default
+
+        # This method will check which system we're on and initialize the correct sub-module.
+        # Currently we only support Ubuntu.
+        #
+        def instance
+          if Gem::Platform.local.ubuntu?
+            UI.debug "#{self}.instance finishes the system check"
+            Base.new
+          else
+            raise 'Sorry, currently only Ubuntu is supported.'
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/csd/application/graphics/about.yml

@@ -0,0 +1,8 @@
+# -*- encoding: UTF-8 -*-
+human: Graphics
+description: Graphic card drivers to improve video quality.
+actions:
+  public:
+    - install: Downloads and installs the latest graphic card driver.
+scopes:
+  --- {}

data/lib/csd/application/graphics/base.rb

@@ -0,0 +1,157 @@
+# -*- encoding: UTF-8 -*-
+require 'csd/application/default/base'
+
+module CSD
+  module Application
+    module Graphics
+      class Base < CSD::Application::Base
+        
+        # This method will notify users about following operations and initiate installation process.
+        # The reason of creating another method to carry out actual installation process is to keep the
+        # source code clean and easy to read.
+        #
+        def install
+          UI.separator
+          UI.info "This operation will download and install the latest graphics card drivers.".green.bold
+          UI.separator
+          introduction
+          install!
+        end
+        
+        # This method is to create a working directory to preserve graphical card installation scripts,
+        # initiate graphics card installation GUI and
+        # clean up the working directory when the graphical card driver has been successfully installed.
+        #
+        def install!
+          define_relative_paths
+          create_working_directory
+          process_graphics_card
+          cleanup_working_directory
+        end
+        
+        def introduction
+          UI.info " Working directory:       ".green.bold + Path.work.to_s.yellow
+          if Options.debug
+            UI.info " Your Platform:           ".green + Gem::Platform.local.humanize.to_s.yellow
+            UI.info(" Application module:      ".green + self.class.name.to_s.yellow)
+          end
+          UI.separator
+          if Options.help
+            UI.info Options.helptext
+            # Cleanup in case the working directory was temporary and is empty
+            Path.work.rmdir if Options.temp and Path.work.directory? and Path.work.children.empty?
+            raise CSD::Error::Argument::HelpWasRequested
+          else
+            raise Interrupt unless Options.yes or Options.reveal or UI.continue?
+          end
+        end
+        
+        # This method will determine the model of graphics card and initiate corresponding installation process
+        # Currently, only Radeon and GeForce graphics cards are supported.
+        #
+        def process_graphics_card
+          case determine_graphic_card
+            when /Radeon/
+              install_radeon
+            when /GeForce/
+              install_geforce
+            else
+              raise Error::Graphics::CardNotSupported, "Sorry, currently only ATI Radeon and nVIDIA GeForce are supported"
+          end
+        end
+        
+        # The method is to detect graphics card model
+        #
+        # ====Returns
+        # * It will return 'Radeon',when options of force_radeon is set.
+        # * It will return 'Radeon',when options of force_radeon is set.
+        # * Otherwise, it will return the result of graphics card checking command.
+        # ====Purpose
+        # This methold is supposed to detect the current graphics card models and initiate corresponding
+        # installation process. However, whenever a user want to force its system to install another graphics
+        # card driver, it will fake the detection result and comply with users' request.
+        #
+        def determine_graphic_card
+          return 'Radeon' if Options.force_radeon
+          return 'GeForce' if Options.force_geforce
+          Cmd.run('lspci | grep VGA', :internal => true).output
+        end
+        
+        def install_radeon
+          Cmd.git_clone 'drivers for ATI radeon', 'git://github.com/csd/ati.git', Path.radeon
+          Cmd.run "chmod +x #{Path.radeon_run}", :announce_pwd => false
+          proprietary_continue
+          Cmd.run "sh #{Path.radeon_run}", :announce_pwd => false
+        end
+        
+        def install_geforce
+          if xserver_running? or Options.reveal
+            UI.separator
+            UI.info 'This operation cannot be performed in the GNOME environment.'.red.bold
+            UI.info 'The AI can stop GNOME for you now. Once this happens, you need'.green.bold
+            UI.info 'to provide your Linux credentials and start the AI again from there.'.green.bold
+            UI.separator
+            if Options.yes or Options.reveal or UI.continue?
+              Cmd.run "sudo /etc/init.d/gdm stop", :announce_pwd => false
+              raise Error::Graphics::XServerStillRunning
+            else
+              raise Interrupt
+            end
+          else
+            Cmd.run "sudo /etc/init.d/gdm start" unless install_geforce!
+            cleanup_working_directory
+          end
+        end
+        
+        def xserver_running?
+          result = Cmd.run('ps -ef', :internal => true)
+          result.success? and (result.output =~ /bin\/X.+gdm/ or result.output =~ /xinit/)
+        end
+        
+        def install_geforce!
+          raise Error::Graphics::Amd64NotSupported, "Sorry, nVIDIA GeForce is currently only supported on x86" unless Gem::Platform.local.cpu == 'x86' 
+          Cmd.git_clone 'drivers for nVIDIA GeForce', 'git://github.com/csd/nvidia.git', Path.geforce
+          Cmd.run "chmod +x #{Path.geforce_run}", :announce_pwd => false
+          proprietary_continue_for_geforce
+          # Note that we cannot use Cmd.run here, because the User input is not forwared to
+          # the executed application correctly. We will use Ruby's native command execution
+          # Cmd.run "sudo #{Path.geforce_run}", :announce_pwd => false, :verbose => true, :die_on_failure => false
+          system "sudo #{Path.geforce_run}"
+        end
+        
+        def proprietary_continue
+          UI.separator
+          UI.info 'The proprietary installer for your graphic card will now be executed.'.green.bold
+          UI.info 'Please follow the instructions manually.'.green.bold
+          UI.separator
+          wait_for_confirmation
+        end
+        
+        def proprietary_continue_for_geforce
+          UI.separator
+          UI.info 'The proprietary installer for your graphic card will now be executed.'.green.bold
+          UI.info 'Be sure to select "Yes" when asked if nvidia-xconfig should update your X configuration.'.green.bold
+          UI.info 'Please restart your computer after exiting the wizard.'.green.bold
+          UI.separator
+          wait_for_confirmation
+        end
+        
+        def wait_for_confirmation
+           unless UI.continue? or Options.reveal
+           cleanup_working_directory
+           raise Interrupt
+          end
+        end
+        
+        def define_relative_paths
+          UI.debug "#{self.class}#define_relative_paths defines relative graphics paths now"
+          Path.radeon       = Pathname.new(File.join(Path.work, 'radeon'))
+          Path.radeon_run   = Pathname.new(File.join(Path.radeon, 'ati-driver-installer-10-7-x86.x86_64.run'))
+          Path.geforce      = Pathname.new(File.join(Path.work, 'geforce'))
+          Path.geforce_run  = Pathname.new(File.join(Path.geforce, 'NVIDIA-Linux-x86-256.44.run.sh'))
+        end
+        
+      end
+    end
+  end
+end