ass_launcher 0.6.0 → 0.7.0

data/en.README.md

@@ -0,0 +1,235 @@
+[![Code Climate](https://codeclimate.com/github/leoniv/ass_launcher/badges/gpa.svg)](https://codeclimate.com/github/leoniv/ass_launcher)
+[![Gem Version](https://badge.fury.io/rb/ass_launcher.svg)](https://badge.fury.io/rb/ass_launcher)
+
+# AssLauncher
+
+Ruby wrapper for 1C:Enterprise platform.
+
+Goal of this to make easily and friendly writing scripts for development
+and support lifecycle of 1C:Enterprise applications
+
+`AssLauncher` is cross platform but **it full tested in `Cygwin` only!**. In  `Windows` and `Linux` it works too.
+
+In `Linux` don't support `OLE` feature. Don't known why I told it ;)
+
+
+## Quick start
+
+### Using `AssLauncher` as a library
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ass_launcher'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ass_launcher
+
+For example, writing script which dumping 1C:Enterprise application
+
+```ruby
+require 'ass_launcher'
+
+include AssLauncher::Api
+
+def main(dupm_path)
+  # Get wrapper for the thck client
+  thick_client = thicks('~> 8.3.8.0').last
+
+  # Fail if 1C:Enterprise installation not found
+  fail '1C:Enterprise not found' if thick_client.nil?
+
+  # Build designer command
+  designer = thick_client.command :designer do
+    _S 'enterprse_server/application_name'
+    dumpIB dupm_path
+  end
+
+  # Execute command
+  designer.run.wait
+
+  # Verify result
+  designer.process_holder.result.verify!
+end
+
+main ARGV[0]
+```
+
+### Command line utility `ass-launcher`
+
+From version `0.3.0` `AssLauncher` provides console tool `ass-launcher` wich has
+features:
+
+- make new 1C:Enterprise application instance (aka information base)
+- run 1C:Enterprise
+- show help about 1C:Enterprise CLI parameters
+- and some more
+
+For more info about `ass-launcher` execute:
+
+    $ass-launcher --help
+
+
+## x86_64 1C:Enterprise for Windows
+
+From `v8.3.9` 1C provides x86_64 arch platform for Windows.
+
+For choosing which arch of 1C binary you need
+`AssLauncher::Enterprise::BinaryWrapper` has `arch` property and some helpers
+in `AssLauncher::Api` like a `*_i386` and `*_x86_64`.
+
+For in-process OLE server `v83.ComConnector` aka `comcntr.dll`, arch of 1C
+binary selects automaticaly in depends of Ruby arch.
+
+On default using of `x86_64` 1C OLE server is forbidden (see below trouble).
+For forcing to use `x86_64` OLE server set config flag `use_x86_64_ole`:
+
+```ruby
+  AssLauncher.configure do |conf|
+    conf.use_x86_64_ole = true
+  end
+```
+
+### Trouble with x86_64 in-process OLE server `v83.ComConnector`
+
+`x86_64` in-process OLE server or Ruby `win32ole` is unstable now
+and Ruby usually crashed while handling connect error.
+
+Еxample for `x86_64` Ruby and 1C OLE server:
+
+```
+$ruby -v
+ruby 2.3.6p384 (2017-12-14 revision 9808) [x86_64-cygwin]
+
+$pry
+
+RbConfig::CONFIG['arch'] #=> "x86_64-cygwin"
+
+require 'win32ole'
+
+inproc = WIN32OLE.new('V83.COMConnector')
+
+inproc.connect('invalid connection string')
+
+....*** buffer overflow detected ***: terminated
+Aborted (стек памяти сброшен на диск)
+```
+
+The same example for `i386` Ruby and 1C OLE server working fine:
+
+```
+$ruby -v
+ruby 2.3.6p384 (2017-12-14 revision 9808) [i386-cygwin]
+
+$pry
+
+RbConfig::CONFIG['arch'] #=> "i386-cygwin"
+
+require 'win32ole'
+
+inproc = WIN32OLE.new('V83.COMConnector')
+
+inproc.connect('invalid connection string')
+
+WIN32OLERuntimeError: (in OLE method `connect': )
+    OLE error code:80004005 in V83.COMConnector.1
+      Неверные или отсутствующие параметры соединения с информационной базой
+    HRESULT error code:0x80020009
+      Exception occurred.
+from (pry):3:in `method_missing'
+```
+
+
+### Trouble with x86_64 local OLE servers `v83c.Application` and `v83.Application`
+
+On theory, architecture of local OLE server isn't important for using them
+in various Ruby architectures.
+
+But it only theory. While in the run [exaples](examples/) in the `i386` Ruby
+with `x86_64` local 1C OLE observes the unexpected behavior of 1C OLE
+servers like a errors while to connect to information base:
+
+```
+WIN32OLERuntimeError: (in OLE method `connect': )
+    OLE error code:0 in <Unknown>
+      <No Description>
+    HRESULT error code:0x80010108
+      The object invoked has disconnected from its clients.
+    /tmp/ass_launcher/lib/ass_launcher/enterprise/ole/win32ole.rb:87:in `method_missing'
+    /tmp/ass_launcher/lib/ass_launcher/enterprise/ole/win32ole.rb:87:in `call'
+    /tmp/ass_launcher/lib/ass_launcher/enterprise/ole/win32ole.rb:87:in `block in <class:WIN32OLE>'
+    /tmp/ass_launcher/lib/ass_launcher/enterprise/ole.rb:142:in `__try_open__'
+    /tmp/ass_launcher/lib/ass_launcher/enterprise/ole.rb:136:in `__open__'
+    /tmp/ass_launcher/examples/enterprise_ole_example.rb:131:in `block (4 levels) in <module:EnterpriseOle>'
+```
+
+## Usage
+
+### Examples
+
+For more usage examples see [examples](examples/)
+
+For beginning look at
+[examples/enterprise_running_example.rb](examples/enterprise_running_example.rb)
+
+All [examples](examples/) executable. For run them require
+1C:Enterprise platform version defined in `Examples::MIN_PLATFORM_VERSION`
+
+Run all examples:
+
+    $rake run_examples
+
+Or run specified example:
+
+    $rake run_examples TEST=examples/enterprise_running_example.rb
+
+### Troubles
+
+Directory [examples/troubles](examples/troubles) contains examples
+which describe troubles with executing 1C:Enterprise binary.
+
+All [examples/troubles](examples/troubles) are executable too.
+
+Run all troubles:
+
+    $rake run_trouble_examples
+
+**Be careful to run [examples/troubles](examples/troubles)! Learn sources before run it.**
+
+## Help
+
+If you have any questions open issue with `question` lable
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+### Development helper
+
+`AssLauncher` include [bin/dev-helper](bin/dev-helper) utility for contributors.
+
+    $bin/dev-helper --help
+
+### Testing
+
+#### Run unit tests:
+
+    $export SIMPLECOV=YES && rake test
+
+Unit tests is isolated and doesn't require installation of 1C:Enterprise
+
+#### Run examples:
+
+Examples writed as `Minitest::Spec`. About run examples see above
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/leoniv/ass_launcher.

data/examples/README.md

@@ -0,0 +1,35 @@
+# Примеры использования *AssLauncher*
+
+В данном каталоге собраны примеры использования *AssLauncher* оформленные как
+исполняемые тесты в формате [Mintest::Spec](https://github.com/seattlerb/minitest).
+Примеры сгруппированы по фичам *AssLauncher*:
+
+- файл [binary_wrappers_example.rb](binary_wrappers_example.rb) - примеры для
+работы с различными видами клиентов платформы 1С
+- файл [arguments_builder_example.rb](arguments_builder_example.rb) - примеры
+работы с построителем аргументов для консольного запуска платформы 1С
+- файл [connection_string_example.rb](connection_string_example.rb) - пример
+работы со строкой соединения
+- файл [create_infobase_example.rb](create_infobase_example.rb) - примеры
+запуска платформы в режиме создания информационной базы
+- файл [enterprise_ole_example.rb](enterprise_ole_example.rb) - примеры работы с
+различными видами 1С OLE серверов
+- файл [enterprise_out_example.rb](enterprise_out_example.rb) - пример захвата
+вывода платформы
+- файл [enterprise_running_example.rb](enterprise_running_example.rb) - базовые
+примеры работы с различными клиентами платформы 1С
+- файл [v8i_file_example.rb](v8i_file_example.rb) - пример работы с файлами v8i
+- файл [webclient_example.rb](webclient_example.rb) - более подробный пример
+работы с web клиентом
+
+Для запуска примеров требуется установленная платформа 1С версии указанной
+в константе `MIN_PLATFORM_VERSION` объявленной в файле
+[example_helper.rb](example_helper.rb)
+
+Запуск примеров:
+
+    $ bundler exec rake run_examples
+
+Запуск с фильтром по имени спеки:
+
+    $ bundler exec rake run_examples TESTOPTS='--name=/здесь рег. выражение/i'

data/examples/create_infobase_example.rb

@@ -38,7 +38,7 @@ module Examples
       end
 
       after do
-        FileUtils.rm_rf conns.file if File.exists?(conns.file)
+        FileUtils.rm_rf conns.file if File.exist?(conns.file)
       end
     end
   end

data/examples/enterprise_ole_example.rb

@@ -8,9 +8,9 @@ module Examples
     end
 
     # 1C:Enterprise provides three OLE servers:
-    # v8x.Application - thick client standalone OLE server
-    # v8xC.Application - thin client standalone OLE server
-    # v8x.ComConnector - inproc ole server for connect to:
+    # v8x.Application - thick client local OLE server
+    # v8xC.Application - thin client local OLE server
+    # v8x.ComConnector - in-process OLE server for connect to:
     #  - 1C:Enterprise application aka infobases
     #  - 1C:Enterprise server agent
     #  - 1C:Enterprise server working process
@@ -72,7 +72,7 @@ module Examples
     end
 
     describe 'Closing connection' do
-      describe 'For standalone server it working perfect' do
+      describe 'For local server it working perfect' do
         extend AssLauncher::Api
         thick_app = ole(:thick, PLATFORM_VER)
 
@@ -97,16 +97,16 @@ module Examples
         end
       end
 
-      describe 'For inproc server close connection working with restrictions' do
-        # 1C inproc OLE servers haven't method for closing connection!
+      describe 'For in-process server close connection working with restrictions' do
+        # 1C in-process OLE servers haven't method for closing connection!
         # Connection keep alive while live ruby process.
         #
-        # If in one ruby script we want to use inproc connection for some work
+        # If in one ruby script we want to use in-process connection for some work
         # do in the infobase and after them we want run other connection
         # or application or designer with flag of exclusive mode, in this case
-        # opened inproc connection doesn't give us to do it
+        # opened in-process connection doesn't give us to do it
         #
-        # AssLauncher provide feature for closing inproc connection  but
+        # AssLauncher provide feature for closing in-process connection  but
         # it working with restrictions.
         #
         # AssLauncher patching WIN32OLE and collect all ole objects which
@@ -116,14 +116,14 @@ module Examples
         # But it works not always. Connection keep alive while have any alive
         # WIN32OLE refs generated this connection
 
-        describe 'Case when inproc server connection realy closed' do
+        describe 'Case when in-process server connection realy closed' do
           extend AssLauncher::Api
 
-          # Get standalone ole server wrapper
+          # Get local ole server wrapper
           # It is service connector
           thick_app = ole(:thick, PLATFORM_VER)
 
-          # Get inproc ole server wrapper
+          # Get in-process ole server wrapper
           # It object under test
           external = ole(:external, PLATFORM_VER)
 
@@ -164,10 +164,10 @@ module Examples
       # AssLauncher automatically register needed server version
       # and returns suitable wrapper.
       #
-      # Registration version of ole server working correct only for standalone
+      # Registration version of ole server working correct only for local
       # servers such as Thin and Thick applications.
       #
-      # We don't get new version of inproc ole server until old version
+      # We don't get new version of in-process ole server until old version
       # is loaded in memory
 
       it "Fail if 1C:Enterprise version doesn't instaled" do
@@ -179,7 +179,7 @@ module Examples
         e.message.must_match %r{Platform version `~> 999' not instaled}
       end
 
-      describe 'Choosing version of standalone ole server working perfect' do
+      describe 'Choosing version of local ole server working perfect' do
         extend AssLauncher::Api
 
         thick_app = ole(:thick, PLATFORM_VER)

data/examples/enterprise_running_example.rb

@@ -49,7 +49,7 @@ module Examples
           # will be passed to arguments builder instance
           connection_string "File=\"#{TMP::EMPTY_IB}\";"
           _L 'en'
-          _Debug
+          _Debug :'-tcp'
           _DebuggerUrl 'tcp://localhost'
         end
 

data/examples/example_helper.rb

@@ -53,7 +53,7 @@ module Examples
     end
 
     def exists?(name)
-      File.exists? ib_file_path(name)
+      File.exist? ib_file_path(name)
     end
 
     def ib_file_path(name)
@@ -103,7 +103,7 @@ module Examples
     module TmpIb
       extend IbMaker
       def self.rm(name)
-        FileUtils.rm_rf ibases[name] if File.exists? ibases[name]
+        FileUtils.rm_rf ibases[name] if File.exist? ibases[name]
       end
 
       def self.ibases_root

data/examples/troubles/README.md

@@ -0,0 +1,20 @@
+# Примеры проблем консольного запуска платформы 1С
+
+Об общих проблемах скриптинга на платформе 1С можно прочесть
+[здесь](https://github.com/leoniv/v8_circles_of_hell/blob/master/articles/круг_первый_скриптинг.md)
+
+Некоторые проблемы консольного запуска платформы проиллюстрированы в форме
+исполняемых тестов расположенных в этом каталоге. Тесты написаны в формате
+[Mintest::Spec](https://github.com/seattlerb/minitest)
+
+Для запуска примеров требуется установленная платформа 1С версии указанной
+в константе `MIN_PLATFORM_VERSION` объявленной в файле
+[../example_helper.rb](../example_helper.rb)
+
+Но прежде чем запустить их изучите исходники.
+
+Запуск используйте команду:
+
+    $bundler exec rake run_trouble_examples SHOW_STUPID_GUI=YES
+
+И не забывайте закрывать окна 1С которые будут появляться в процессе тестов.

data/examples/troubles/with_creteinfobase_example.rb

@@ -28,7 +28,7 @@ module Examples
         command.run.wait
 
         # Infobase which we want not exists
-        File.exists?(conns.file).must_equal false
+        File.exist?(conns.file).must_equal false
 
         # But created infobase which we don't want
         skip 'It fixed from 1C:Enterprise 8.3.10'
@@ -38,7 +38,7 @@ module Examples
         created = Regexp.last_match[1]
         created.must_match(/InfoBase\D?/i)
 
-        File.exists?(created).must_equal true
+        File.exist?(created).must_equal true
       end
 
       it 'Creates infobase which we want' do
@@ -62,11 +62,11 @@ module Examples
           /Creation of infobase \("File\s?=\s?'([^']+)/i
         created = Regexp.last_match[1]
         command.args[1].must_include created
-        File.exists?(conns.file).must_equal true
+        File.exist?(conns.file).must_equal true
       end
 
       after do
-        FileUtils.rm_rf conns.file if File.exists? conns.file
+        FileUtils.rm_rf conns.file if File.exist? conns.file
       end
 
       describe 'Solution with AssLauncher' do
@@ -88,7 +88,7 @@ module Examples
         .path(infobasedir).win_string
 
       before do
-        FileUtils.rm_rf infobasedir if File.exists? infobasedir
+        FileUtils.rm_rf infobasedir if File.exist? infobasedir
       end
 
       it "Fails if connection string double quoted" do
@@ -132,11 +132,11 @@ module Examples
         created = Regexp.last_match[1]
 
         conns.file.must_equal created
-        File.exists?(conns.file).must_equal true
+        File.exist?(conns.file).must_equal true
       end
 
       after do
-        FileUtils.rm_rf infobasedir if File.exists? infobasedir
+        FileUtils.rm_rf infobasedir if File.exist? infobasedir
       end
     end
 
@@ -147,7 +147,7 @@ module Examples
                               'example_create_infobase_with_right_slashes.ib')
 
       before do
-        FileUtils.rm_rf infobasedir if File.exists? infobasedir
+        FileUtils.rm_rf infobasedir if File.exist? infobasedir
       end
 
       describe 'Using single quote in connection string' do
@@ -199,12 +199,12 @@ module Examples
           end
 
           # Realy infobase not exists
-          File.exists?(infobasedir).must_equal false
+          File.exist?(infobasedir).must_equal false
         end
       end
 
       after do
-        FileUtils.rm_rf infobasedir if File.exists? infobasedir
+        FileUtils.rm_rf infobasedir if File.exist? infobasedir
       end
     end
 
@@ -242,9 +242,9 @@ module Examples
           end
 
           # Realy infobase not exists
-          File.exists?(infobasedir).must_equal false
+          File.exist?(infobasedir).must_equal false
           # Infobase created in the current directory created
-          File.exists?(infobasedir.gsub('..','.')).must_equal true
+          File.exist?(infobasedir.gsub('..','.')).must_equal true
 
         end
       end
@@ -282,7 +282,7 @@ module Examples
       end
 
       after do
-        FileUtils.rm_rf infobasedir if File.exists? infobasedir
+        FileUtils.rm_rf infobasedir if File.exist? infobasedir
       end
     end
 
@@ -300,7 +300,7 @@ module Examples
 
           extend AssLauncher::Api
 
-          File.exists?(root).must_equal true
+          File.exist?(root).must_equal true
           conns = cs_file file: infobasedir
 
           command = CLIENTS::THICK.command :createinfobase,
@@ -316,7 +316,7 @@ module Examples
 
       describe 'Using double quoted connection string' do
         it 'Infobase is created not where you need' do
-          File.exists?(root).must_equal true
+          File.exist?(root).must_equal true
           conns = "File=\"#{infobasedir}\""
 
           command = CLIENTS::THICK.command :createinfobase,
@@ -342,16 +342,16 @@ module Examples
           end
 
           # Realy infobase not exists
-          File.exists?(infobasedir).must_equal false
+          File.exist?(infobasedir).must_equal false
         end
       end
 
       before do
-        FileUtils.rm_rf infobasedir if File.exists? infobasedir
+        FileUtils.rm_rf infobasedir if File.exist? infobasedir
       end
 
       after do
-        FileUtils.rm_rf infobasedir if File.exists? infobasedir
+        FileUtils.rm_rf infobasedir if File.exist? infobasedir
       end
     end
 
@@ -366,7 +366,7 @@ module Examples
       it 'Solution with ConnectionString::File' do
         extend AssLauncher::Api
 
-        File.exists?(root).must_equal true
+        File.exist?(root).must_equal true
         # ConnectionString::File converts connection string
         # for CREATEINFOBASE mode from double quoted:
         # 'File="pat";' to single quoted: "File='path';" string
@@ -384,12 +384,12 @@ module Examples
         created = Regexp.last_match[1]
 
         conns.file.must_equal created
-        File.exists?(conns.file).must_equal true
+        File.exist?(conns.file).must_equal true
       end
 
       describe 'Using double quoted connection string' do
         it 'Fails CREATEINFOBASE' do
-          File.exists?(root).must_equal true
+          File.exist?(root).must_equal true
           conns = "File=\"#{infobasedir}\""
 
           command = CLIENTS::THICK.command :createinfobase,
@@ -408,11 +408,11 @@ module Examples
       end
 
       before do
-        FileUtils.rm_rf infobasedir if File.exists? infobasedir
+        FileUtils.rm_rf infobasedir if File.exist? infobasedir
       end
 
       after do
-        FileUtils.rm_rf infobasedir if File.exists? infobasedir
+        FileUtils.rm_rf infobasedir if File.exist? infobasedir
       end
     end
   end