[Rubygems-developers] Please review GemspecReference

[Austin Ziegler]

Hi. I've been lurking a couple of days, since the discussion on
using Ruwiki. I am continuing work, but am very busy socially this
weekend.

1. Certain spec items are listed as optional strings, when in
   reality they should be optional strings or arrays. After all, I
   didn't write Ruwiki or Minitar by myself. I should be able to do:

        # Minitar
      spec.author = %w(Austin\ Ziegler Mauricio\ Fernandez)

   RubyGems should do the right thing at this point. The spec items
   that should apply this way are #author, #email, #homepage (some
   of my projects are in transition and have multiple home pages as
   of yet; the example reads "spec.hompage", by the way).

2. #bindir: shouldn't this be #exec -- as in the ./configure option
   of --exec-prefix ?

3. #date: If I want to manually set a Gem to a specific date/time,
   would I set #date? When I release, I generally make sure that my
   files have the proper date/time values for the release date/time.
   How would I use this?

4. #default_executable: is this an attempt to get to the idea of an
   executable .jar as in Java? Will the gem actually be unpacked?

5. #dependencies: The item reads:
      spec.add_dependency('log4r', '> = 1.0.5')
   Shouldn't that be ">= 1.0.5"? Also, what are all of the version
   comparison options? In a separate email, Gavin suggested that
   there's a ~> 1.0.5 which will give all versions 1.0.5 - 1.0.9,
   but not 1.1.0. Is there? Where are these documented?

   Also, with #requirements, could there be a way for me to provide a
   program that tests for dependencies that may be present? Basically, if my
   program detects that the requirements are met either with or without a
   Gem, then it should be able to tell RubyGems to continue the
   installation. Also, I want to specify *optional* dependencies. I am
   looking at finally packaging the old programs I have, and Text::Format
   has an optional dependency on TeX::Hyphen. I'm going to be providing
   TeX::Hyphen as a gem, and Gems should offer to install it when installing
   Text::Format, but should not require it for installation.

6. #description: Um. I *don't* actually like that the formatting is
   removed. Many of my README files look like:

      Package Name README
      -------------------
      blah blah blah

   This is turned into "Package Name README ------------------- blah
   blah blah". If you're going to recommend reading in the README
   file, then provide me a way to force my formatting to be kept;
   otherwise, don't suggest that :) As it is, I'm reading the first
   paragraph in and chopping off the first two lines.

7. #executables: is it mandatory that I don't specify the full
   relative path, or is this changing? I can potentially see cases
   where I want to specify both files in bin/ and not in bin/.
   Maybe. I'm not 100% comfortable with RubyGems' handling of
   executables in the first place. For my latest work with Ruwiki, I
   actually have:

      load_state = 1
      begin
        if 1 == load_state
          require 'rubygems'
          require_gem 'ruwiki', '=0.8.1'
        else
          require 'ruwiki'
        end
      rescue LoadError
        load_state += 1

        case load_state
        when 3
          $LOAD_PATH.unshift "#{File.dirname($0)}/../lib"
        when 4
          $LOAD_PATH.shift
          $LOAD_PATH.unshift "#{File.dirname(__FILE__)}/../lib"
        when 5
          raise
        end
        retry
      end

      require 'ruwiki/utils'
      require 'ruwiki/utils/manager'

      ss = "#{File.dirname(File.expand_path(__FILE__))}/shared"

      Ruwiki::Utils::Manager.shared = ss

      exit Ruwiki::Utils::Manager.run(ARGV)

   In other words, I've basically written the stub for you. I'm
   still not sure how to handle the "ss" value -- that's one of the
   things that's slowing me down from finalising a Ruwiki Rubygem
   (the other being a 0.8.0 release). Also, there were some issues
   in the installation of stubs -- I think specifically the binary
   stubs -- in that the version required was the last installed, not
   the latest version. Further, has any consideration been given on
   how to run alternative versions of binaries? If I want to have
   Ruwiki 0.8.1 and Ruwiki 0.9.0 on my system, can I do:

      gem run ruwiki --version=0.8.1 bin/ruwiki_servlet

   (Obviously, I can't, but how would I do that?)

   The generated .cmd file on Windows is bad. First, it should be
   .bat for Win9x and WinNT/XP can handle .bat as if it were .cmd.
   Second, it reads:

      @ruby C:/Apps/Ruby18/bin/ldiff %1 %2 %3 %4 %5 %6 %7 %8 %9

   It *should* read:

      @echo off
      if "%OS%"=="Windows_NT" goto WinNT
      <ruby> -x "<command>" %1 %2 %3 %4 %5 %6 %7 %8 %9
      goto done
      :WinNT
      <ruby> -x "<command>" %*
      goto done
      :done

   In my installer, I do:

      cfg = Config::CONFIG
      WRAPPER.gsub('<ruby>', File.join(cfg['bindir'],
                                       cfg['ruby_install_name']).
                                  gsub(%r{/}) { "\\" }).
              gsub!('<command>', File.join(cfg['bindir'], op_file).
                                  gsub(%r{/}) { "\\" } )

   op_file is the name of the file that I'm processing. If my user
   is using a modern Windows OS, then do not limit me to nine
   parameters; %* works on Windows NT/2000/XP/2003 in the same way
   that $* works on Unixes. (Actually, I think it may work more like
   $@.)

8. #platform: Can we get this optional defaulting to Gem::Platform::Ruby? It
   seems silly that this is required if you aren't specifying a default
   platform.

9. #summary: Perhaps if #summary is not specified and #description is, the
   first sentence of #description can be used for #summary?

-austin