flgen 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c98696eca3ffddc4f49695ec9fe26ad40bebaa8b4ef432a9a24455059ec675f
-  data.tar.gz: 2d4cacf96065ceeebf2c5a662fd0d2f2706e9fb97363a3990eec9e77d06d1ad8
+  metadata.gz: bcca98956f35047f290608dcbbf1020017006475cc0d139c05ab070b19d47aa3
+  data.tar.gz: f1f2bb32ae9a4fd5c3466d6a375573fdc6b6944a8130e6c6be03d558f5ac4f58
 SHA512:
-  metadata.gz: '065852d3c973c0a108e1fccaea7cf7219e9c734fe9f75adff152ddd05df406fe8cb3d92a1a6281bf5494b22d279c60b7d69ba2eec0a104fcfe6a6badbda1dcfe'
-  data.tar.gz: 70eb64d338dad8169c3a577228b4640fa91c4e5645aa8432401996aa95696a53cca8d5d0e2d1b01568e0a7082b1a00fd0692a4650c508a9945cf56e420d1429a
+  metadata.gz: 3fea45a268196454d145a21af8c2ac56d62ae6a53aae99851d88dc1a8f3b78b74af4f44b461d60e73b71fcbce3cde24e1d39bf19eeddae1d8d8de81a21550580
+  data.tar.gz: d116c3598283c4e52501e544e8159270776caaff3486a5c8bba77e38de82c4f699ac0b0948e78bd9a2bdaef27a6dfa834594dec15ddb0ef6e629f13ea44ceec0

data/README.md

@@ -1,76 +1,86 @@
+[![Gem Version](https://badge.fury.io/rb/flgen.svg)](https://badge.fury.io/rb/flgen)
 [![CI](https://github.com/pezy-computing/flgen/actions/workflows/ci.yml/badge.svg)](https://github.com/pezy-computing/flgen/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/github/pezy-computing/flgen/branch/master/graph/badge.svg?token=P5JSMPRV3J)](https://codecov.io/github/pezy-computing/flgen)
 
 # FLGen
 
-ファイルリストを記述するための DSL と、ファイルリストを生成するための実行コマンドを提供します。
+FLGen provides a DSL to write filelists and generator tool to generate a filelist which is given to EDA tools.
 
-## インストール
+## Install
 
 ### Ruby
 
-FLGen は [Ruby](https://www.ruby-lang.org) で実装されているので、実行には Ruby のインストールが必要です。
-サポートする Ruby のバージョンは 3.0 以上です。インストール方法については、[こちら](https://www.ruby-lang.org/en/downloads/)を参照ください。
+FLGen is written in [Ruby](https://www.ruby-lang.org) programing language and its required version is 3.0 or later. Before using FLGen, you need to install Ruby before using FLGen. See [this page](https://www.ruby-lang.org/en/downloads/) for further details.
 
-### インストールコマンド
+### Install FLGen
 
-FLGen をインストールするには、以下のコマンドを実行します。
+Use the command below to isntall FLGen.
 
 ```
 $ gem install flgen
 ```
 
-## DSL
+## Filelist
 
-ファイルリストを記述するための DSL として以下の構文が定義されています。
+FLGen prives APIs listed below to describe your filelists.
 
-* `source_file(path, from: :current)`
-    * 指定したファイルをファイルリストに追加します
-* `file_list(path, from: :root)`
-    * 指定したファイルリストを読み込みます
+* `source_file(path, from: :current, base: nil)`
+    * Add the given source file to the current filelist.
+* `file_list(path, from: :root, base: nil)`
+    * Load the given filelist.
+* `include_directory(path, from: :current, base: nil)`
+    * Add the given directory to the list of include direcotries.
 * `define_macro(name, value = nil)`
-    * マクロを定義します
-* `macro_defined?(name)`
-    * 指定したマクロが定義されているかどうかを返します
-* `include_directory(path, from: :current)`
-    * 指定したパスをインクルードパスとして追加します
-* `target_tool?(tool)`
-    * `tool` が対象ツールかどうかを返します
+    * Define a text macro.
+* `macro?(name)`/`macro_defined?(name)`
+    * Return `true` if the given macro is defined.
+* `file?(path, from: :current, base: nil)`
+    * Return `treu` if the given file exists.
+* `directory?(path, from: :current, base: nil)`
+    * Return `true` if the given directory exists.
+* `env?(name)`
+    * Return `true` if the givne environment variable is defined.
+* `env(name)`
+    * Retunr the value of the given environment variable.
 * `compile_argument(argument, tool: nil)`
-    * コンパイル引数を追加します
-    * `tool` が指定されている場合は、対象ツールの場合にのみ、引数を追加します
-* `runtime_argument(argument, tool: nil)`
-    * 実行時引数を追加します
-    * `tool` が指定されている場合は、対象ツールの場合にのみ、引数を追加します
+    * Add the given argument to the list of compile arguments.
+    * If `tool` is specified the given argument is added only when `tool` is matched with the targe tool.
+* `runtime_argumetn(argument, tool: nil)`
+    * Add the given argument to the list of runtime arguments.
+    * If `tool` is specified the given argument is added only when `tool` is matched with the targe tool.
+* `target_tool?(tool)`
+    * Return `true` if the given tool is matched with the targe tool.
 
-Ruby の言語内 DSL として実装されているので、以下の様に `if` など Ruby の構文も使用することができます。
+FLGen's filelist is designed as an inernal DSL with Ruby. Therefore you can use Ruby's syntax. For example:
 
 ```ruby
-if target_tool? :vcs
-  compile_argument '-sverilog'
-end
-
-10.times do |i|
-  source_file "foo_#{i}.sv"
+if macro? :GATE_SIM
+  source_file 'foo_top.v.gz' # synthsized netlist
+else
+  source_file 'foo_top.sv' # RTL
 end
 ```
 
-### `from` オプション引数について
+### About `from`/`base` arguments
 
-`from` は指定されたファイルやディレクトリの基準ディレクトリを指定する引数で、`:current`/`root`/`local_root` を指定することができます。
+The `from` argument is to specify how to search the given file or directory. You can specify one of three below.
 
 * `:current`
-    * 現在のファイルリストがある場所を基準とします
+    * Search the given file or directory from the directory where the current filelist is.
 * `:root`
-    * `.git` があるリポジトリのルートディレクトリを基準ディレクトリとします
-    * あるリポジトリのサブモジュール (上位階層にも `.git` がある) 場合、上位リポジトリのルートディレクトリから順に検索を行います
+    * Search the given file or directory from the repository root directories where the `.git` directory is.
+    * Serch order is descending order.
+        * from upper root direcotries to local root direcoty
 * `:local_root`
-    * 自身が含まれるリポジトリのルートディレクトリを基準ディレクトリとします
+    * Search the given file or directory from the repository root directory where the current filelist belongs to.
+
+The `from` argument is ignored if the given path is an absolute path or the `base` argument is specified.
 
-ただし、与えられたファイルやディレクトリが絶対パスで指定されている場合は、`from` に関係なく、そのまま追加されます。
+The `base` argument is to specify the serach direcotry for the given file or directory.
 
-#### 例
+#### Example
 
-以下のディレクトリ構造になっていたとします。
+This is an exmaple directory structure.
 
 ```
 foo_project
@@ -86,61 +96,85 @@ foo_project
     `-- common.sv
 ```
 
-* `bar.list.rb` で `source_file 'bar.sv', from: :current` とある場合
-    * `foo_project/bar_project/src/bar.sv` が追加される
-* `bar.list.rb` で `source_file 'common/common.sv', from: :root` とある場合
-    * `foo_project/common/common.sv` が追加される
-* `bar.list.rb` で `source_file 'common/common.sv', from: :local_root` とある場合
-    * `foo_project/bar_project/common/common.sv` が追加される
+* `source_file 'bar.sv', from: :current` @ `bar.list.rb`
+    * `foo_project/bar_project/bar.sv` is added.
+* `source_file 'common/common.sv', from: :root` @ `bar.list.rb`
+    * `foo_project/common/common.sv` is added
+* `source_file 'common/bar_common.sv', from: :local_root` @ `bar.list.rb`
+    * `foo_project/bar_project/common/common.sv` is added
 
-## 実行コマンド
+## Generator command
 
-`flgen` が実行コマンドです。`flgen` に DSL で記述されたファイルリストを与えると、EDA ツールに与えるためのファイルリストを出力します。
-また、以下のオプションがあります。
+`flgen` is the generator command and generate a filelist which is given to EDA tools from the given filelists. Command line options are listed below.
 
 * `--define-macro=MACRO[,MACRO]`
-    * マクロ定義を追加します
+    * Define the given macros
 * `--include-directory=DIR[,DIR]`
-    * インクルードディレクトリを追加します
+    * Specify include directories
 * `--compile`
-    * 出力されるファイルリストは `runtime_argument` で指定された実行時引数を含みません
+    * If this option is specified the generated filelist contains source file path, arguments to define macros, arguments to specify include directories and arguments specified by `compile_argument` API.
 * `--runtime`
-    * 出力されるファイルリストは `runtime_argument` で指定された実行時引数だけを含みます
+    * If this option is specified the generated filelist contains arguments specified by `runtime_argumetn`
 * `--tool=TOOL`
-    * 対象となる EDA ツールを指定します
-    * `compile_argument`/`runtime_argument` でツールの指定がある場合、一致する引数がファイルリストに出力されます
+    * Specify the target tool.
 * `--rm-ext=EXT[,EXT]`
-    * 指定された拡張子をソースファイルから削除します
+    * Remove specifyed file extentions from source file path.
 * `--collect-ext=EXT[,EXT]`
-    * 指定された拡張子を持つソースファイルのみがファイルリストに出力されます
+    * The generated filelist contains source file pash which has the specified file extentions.
+* `--format=FORMAT`
+    * Specify the format of the generated filelist.
+    * If no format is specified the generated filelist is for major EDA tools.
+    * If `filelist-xsim` is specified the generated filelist is for Vivado Simulator.
 * `--output=FILE`
-    * 出力するファイルリストのファイル名を指定します
-    * 指定がない場合は、標準出力に出力されます
+    * Specify the path of the generated filelist
+    * The generated fileslist is output to STDOUT if no path is specified.
 * `--[no-]print-header`
-    * ヘッダーを出力するかどうかを指定します。
+    * Specify whether or not the output filelist includes its file header or not.
 * `--source-file-only`
-    * ソースファイルのみがファイルリストに出力されます
+    * The generated filelist contains source file path only if this option is specified.
 
-## サンプル
+## Example
 
-https://github.com/pezy-computing/flgen/tree/master/sample
+You can find an exmpale from [here](https://github.com/pezy-computing/flgen/tree/master/sample).
 
-にサンプルがあります。
+```
+$ flgen --output=filelist.f sample/foo.list.rb
+$ cat filelist.f
+//  flgen version 0.14.0
+//  applied arguments
+//    --output=filelist.f
+//    sample/foo.list.rb
++define+BAR_0
++define+BAR_1=1
++incdir+/home/taichi/workspace/pezy/flgen/sample/bar
++incdir+/home/taichi/workspace/pezy/flgen/sample/bar/baz
+-foo_0
+/home/taichi/workspace/pezy/flgen/sample/foo.sv
+/home/taichi/workspace/pezy/flgen/sample/bar/bar.sv
+/home/taichi/workspace/pezy/flgen/sample/bar/baz/baz.sv
+```
+
+[rggen-sample-testbench](https://github.com/rggen/rggen-sample-testbench) uses FLGen. This can be a practical example.
 
-## ライセンス
+* https://github.com/rggen/rggen-sample-testbench/blob/master/env/compile.rb
+* https://github.com/rggen/rggen-sample-testbench/blob/master/rtl/compile.rb
 
-Apache-2.0 ライセンスの元で公開しています。詳しくは、下記及び [LICENSE](LICENSE) を参照ください。
+## License
 
-    Copyright 2022 PEZY Computing K.K.
+FLGen is licensed under the Apache-2.0 license. See [LICNESE](LICENSE) and below for further details.
 
-    Licensed under the Apache License, Version 2.0 (the "License");
-    you may not use this file except in compliance with the License.
-    You may obtain a copy of the License at
+```
+Copyright 2022 PEZY Computing K.K.
 
-        http://www.apache.org/licenses/LICENSE-2.0
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-    Unless required by applicable law or agreed to in writing, software
-    distributed under the License is distributed on an "AS IS" BASIS,
-    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-    See the License for the specific language governing permissions and
-    limitations under the License.
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```

data/lib/flgen/file_list.rb

@@ -8,27 +8,47 @@ module FLGen
       @root_directories = extract_root
     end
 
-    def file_list(path, from: :root, raise_error: true)
-      root = find_root(path, from, :file?)
-      load_file_list(root, path, raise_error)
+    def file_list(path, from: :root, base: nil, raise_error: true)
+      location = caller_location
+      load_file_list(path, from, base, location, raise_error)
     end
 
-    def source_file(path, from: :current, raise_error: true)
-      root = find_root(path, from, :file?)
-      add_source_file(root, path, raise_error)
+    def source_file(path, from: :current, base: nil, raise_error: true)
+      location = caller_location
+      add_source_file(path, from, base, location, raise_error)
     end
 
     def define_macro(macro, value = nil)
       @context.define_macro(macro, value)
     end
 
-    def macro_defined?(macro)
+    def macro?(macro)
       @context.macros.include?(macro.to_sym)
     end
 
-    def include_directory(path, from: :current, raise_error: true)
-      root = find_root(path, from, :directory?)
-      add_include_directory(root, path, raise_error)
+    alias_method :macro_defined?, :macro?
+
+    def include_directory(path, from: :current, base: nil, raise_error: true)
+      location = caller_location
+      add_include_directory(path, from, base, location, raise_error)
+    end
+
+    def file?(path, from: :current, base: nil)
+      location = caller_location
+      !lookup_root(path, from, base, location, :file?).nil?
+    end
+
+    def directory?(path, from: :current, base: nil)
+      location = caller_location
+      !lookup_root(path, from, base, location, :directory?).nil?
+    end
+
+    def env?(name)
+      ENV.key?(name.to_s)
+    end
+
+    def env(name)
+      ENV.fetch(name.to_s, nil)
     end
 
     def target_tool?(tool)
@@ -61,36 +81,11 @@ module FLGen
       File.exist?(path.join('.git').to_s)
     end
 
-    def find_root(path, from, checker)
-      if absolute_path?(path)
-        ''
-      elsif from == :current
-        current_directory
-      else
-        lookup_root(path, from, checker)
+    def load_file_list(path, from, base, location, raise_error)
+      unless (root = lookup_root(path, from, base, location, :file?))
+        raise_no_entry_error(path, location, raise_error)
+        return
       end
-    end
-
-    def absolute_path?(path)
-      Pathname.new(path).absolute?
-    end
-
-    def current_directory
-      # From Ruby 3.1 Thread::Backtrace::Location#absolute_path returns nil
-      # for code string evaluated by eval methods
-      # see https://github.com/ruby/ruby/commit/64ac984129a7a4645efe5ac57c168ef880b479b2
-      location = caller_locations(3, 1).first
-      path = location.absolute_path || location.path
-      File.dirname(path)
-    end
-
-    def lookup_root(path, from, checker)
-      (from == :root && @root_directories || [@root_directories.last])
-        .find { |root| File.__send__(checker, File.join(root, path)) }
-    end
-
-    def load_file_list(root, path, raise_error)
-      entry_exist?(root, path, :file?, raise_error) || return
 
       # Need to File.realpath to resolve symblic link
       list_path = File.realpath(concat_path(root, path))
@@ -105,26 +100,68 @@ module FLGen
       @context.loaded_file_lists.include?(path)
     end
 
-    def add_source_file(root, path, raise_error)
-      entry_exist?(root, path, :file?, raise_error) || return
+    def add_source_file(path, from, base, location, raise_error)
+      unless (root = lookup_root(path, from, base, location, :file?))
+        raise_no_entry_error(path, location, raise_error)
+        return
+      end
+
       @context.add_source_file(root, path)
     end
 
-    def add_include_directory(root, path, raise_error)
-      entry_exist?(root, path, :directory?, raise_error) || return
+    def add_include_directory(path, from, base, location, raise_error)
+      unless (root = lookup_root(path, from, base, location, :directory?))
+        raise_no_entry_error(path, location, raise_error)
+        return
+      end
 
       directory_path = concat_path(root, path)
       @context.add_include_directory(directory_path)
     end
 
-    def entry_exist?(root, path, checker, raise_error)
-      result = root && File.__send__(checker, concat_path(root, path)) || false
-      result ||
-        raise_error && (raise NoEntryError.new(path, caller_locations(3, 1)[0]))
+    def caller_location
+      caller_locations(2, 1).first
+    end
+
+    def lookup_root(path, from, base, location, checker)
+      search_root(path, from, base, location)
+        .find { |root| File.__send__(checker, concat_path(root, path)) }
+    end
+
+    def search_root(path, from, base, location)
+      if absolute_path?(path)
+        ['']
+      elsif !base.nil?
+        [base]
+      elsif from == :current
+        [current_directory(location)]
+      elsif from == :local_root
+        [@root_directories.last]
+      else
+        @root_directories
+      end
+    end
+
+    def absolute_path?(path)
+      Pathname.new(path).absolute?
+    end
+
+    def current_directory(location)
+      # From Ruby 3.1 Thread::Backtrace::Location#absolute_path returns nil
+      # for code string evaluated by eval methods
+      # see https://github.com/ruby/ruby/commit/64ac984129a7a4645efe5ac57c168ef880b479b2
+      path = location.absolute_path || location.path
+      File.dirname(path)
     end
 
     def concat_path(root, path)
       File.expand_path(path, root)
     end
+
+    def raise_no_entry_error(path, location, raise_error)
+      return unless raise_error
+
+      raise NoEntryError.new(path, location)
+    end
   end
 end

data/lib/flgen/file_list_xsim_formatter.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module FLGen
+  class FileListXsimFormatter < Formatter
+    def format_header_line(line)
+      "//  #{line}"
+    end
+
+    def format_macro(macro, value)
+      if value.nil?
+        "-d #{macro}"
+      else
+        "-d #{macro}=#{value}"
+      end
+    end
+
+    def format_include_directory(directory)
+      "-i #{directory}"
+    end
+
+    def fomrat_argument(argument)
+      argument
+    end
+
+    def format_file_path(path)
+      path
+    end
+
+    Formatter.add_formatter(:'filelist-xsim', self)
+  end
+end

data/lib/flgen/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FLGen
-  VERSION = '0.14.0'
+  VERSION = '0.15.0'
 end

data/lib/flgen.rb

@@ -11,4 +11,5 @@ require_relative 'flgen/file_list'
 require_relative 'flgen/context'
 require_relative 'flgen/formatter'
 require_relative 'flgen/file_list_formatter'
+require_relative 'flgen/file_list_xsim_formatter'
 require_relative 'flgen/cli'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flgen
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Taichi Ishitani
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-12-16 00:00:00.000000000 Z
+date: 2023-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bump
@@ -80,6 +80,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.40.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+- !ruby/object:Gem::Dependency
+  name: simplecov-cobertura
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.1.0
 description: Filelist generator
 email:
 - ishitani@pezy.co.jp
@@ -98,6 +126,7 @@ files:
 - lib/flgen/exceptions.rb
 - lib/flgen/file_list.rb
 - lib/flgen/file_list_formatter.rb
+- lib/flgen/file_list_xsim_formatter.rb
 - lib/flgen/formatter.rb
 - lib/flgen/source_file.rb
 - lib/flgen/version.rb
@@ -130,7 +159,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.4.2
 signing_key: 
 specification_version: 4
 summary: Filelist generator