bootsnap 1.1.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 0ecc363422058c3f1f15e26b8aafa41d3abf3e67
-  data.tar.gz: 8dccbbc4ea0340eae49f8df2bf3295e16596d91f
+SHA256:
+  metadata.gz: a6aa25eb064ffeb1bd2e7588f6741061c1acd0647782ba830ebc872ce8997ff2
+  data.tar.gz: 981babf7f6d1dc70cd02e5b7373a1a0770d3ebca39e1488503e7aebc1665f8f2
 SHA512:
-  metadata.gz: 9a3ffe705bcc35a61bfdd1560ae3807172dc82532384ae9d87da91e790568c4e0abf925378f4f9d6611e8cea469dd8f70793ac4d2edc39f86181b3a6a2102049
-  data.tar.gz: bb19b804f025c65af27daedb086fdadd8b8978d3d404ccef045b0f3361ca2719ee961b5c66f81b608294d2191595875de47e06f816eb330ed97f2c33884e23e9
+  metadata.gz: 5dc67fe4306e38465bbcec301a169e42a7555ce5541b3d2032cfdf157bf4ff47a25b4403a450f57232f2ae27c69fee8f284fdc94588e671b33af9edff5b6fc2d
+  data.tar.gz: de7d7384d6cb6c97b7e32ebf6f00de0e7b9f7a0aa65a76897d0458a1d0a172e8d714ca3d812ed79aef9a34943ef7dcfdbff95413c95dab4d44be13971dd2cf57

data/.rubocop.yml

@@ -4,4 +4,17 @@ inherit_from:
 AllCops:
   Exclude:
     - 'vendor/**/*'
+    - 'tmp/**/*'
+  TargetRubyVersion: '2.2'
 
+# This doesn't take into account retrying from an exception
+Lint/HandleExceptions:
+  Enabled: false
+
+# allow String.new to create mutable strings
+Style/EmptyLiteral:
+  Enabled: false
+
+# allow the use of globals which makes sense in a CLI app like this
+Style/GlobalVars:
+  Enabled: false

data/.travis.yml

@@ -1,5 +1,13 @@
-os: osx
 language: ruby
-rvm: ruby-2.4.0
+sudo: false
+
+os:
+  - linux
+  - osx
+
+rvm:
+  - ruby-2.4
+  - ruby-2.5
+
 before_script: rake
-script: bin/testunit
+script: bundle exec bin/testunit

data/CHANGELOG.md

@@ -1,3 +1,46 @@
+# 1.3.0
+
+* Handle cases where load path entries are symlinked (https://github.com/Shopify/bootsnap/pull/136)
+
+# 1.2.1
+
+* Fix method visibility of `Kernel#require`.
+
+# 1.2.0
+
+* Add `LoadedFeaturesIndex` to preserve fix a common bug related to `LOAD_PATH` modifications after
+  loading bootsnap.
+
+# 1.1.8
+
+* Don't cache YAML documents with `!ruby/object`
+* Fix cache write mode on Windows
+
+# 1.1.7
+
+* Create cache entries as 0775/0664 instead of 0755/0644
+* Better handling around cache updates in highly-parallel workloads
+
+# 1.1.6
+
+* Assortment of minor bugfixes
+
+# 1.1.5
+
+* bugfix re-release of 1.1.4
+
+# 1.1.4 (yanked)
+
+* Avoid loading a constant twice by checking if it is already defined
+
+# 1.1.3
+
+* Properly resolve symlinked path entries
+
+# 1.1.2
+
+* Minor fix: deprecation warning
+
 # 1.1.1
 
 * Fix crash in `Native.compile_option_crc32=` on 32-bit platforms.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at burke@libbey.me. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -2,3 +2,7 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in bootsnap.gemspec
 gemspec
+
+group :development do
+  gem 'rubocop'
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Shopify, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.jp.md

@@ -0,0 +1,229 @@
+# Bootsnap [![Build Status](https://travis-ci.org/Shopify/bootsnap.svg?branch=master)](https://travis-ci.org/Shopify/bootsnap)
+
+Bootsnap は RubyVM におけるバイトコード生成やファイルルックアップ等の時間のかかる処理を最適化するためのライブラリです。ActiveSupport や YAML もサポートしています。[内部動作](#内部動作)もご覧ください。
+
+注意書き: このライブラリは英語話者によって管理されています。この README は日本語ですが、日本語でのサポートはしておらず、リクエストにお答えすることもできません。バイリンガルの方がサポートをサポートしてくださる場合はお知らせください！:)
+
+### パフォーマンス
+
+* [Discourse](https://github.com/discourse/discourse) では、約6秒から3秒まで、約50%の起動時間短縮が確認されています。
+* 小さなアプリケーションでも、50%の改善（3.6秒から1.8秒）が確認されています。
+* 非常に巨大でモノリシックなアプリである Shopify のプラットフォームでは、約25秒から6.5秒へと約75％短縮されました。
+
+## 使用方法
+
+この gem は MacOS と Linux で作動します。まずは、`bootsnap` を `Gemfile` に追加します:
+
+```ruby
+gem 'bootsnap', require: false
+```
+
+Rails を使用している場合は、以下のコードを、`config/boot.rb` 内にある `require 'bundler/setup'` の直後に追加してください。
+
+```ruby
+require 'bootsnap/setup'
+```
+
+この require の仕組みは[こちら](https://github.com/Shopify/bootsnap/blob/master/lib/bootsnap/setup.rb)で確認できます。
+
+Rails を使用していない場合、または、より多くの設定を変更したい場合は、以下のコードを `require 'bundler/setup'` の直後に追加してください(早く読み込まれるほど、より多くのものを最適化することができます）。
+
+```ruby
+require 'bootsnap'
+env = ENV['RAILS_ENV'] || "development"
+Bootsnap.setup(
+  cache_dir:            'tmp/cache',          # キャッシュファイルを保存する path
+  development_mode:     env == 'development', # 現在の作業環境、例えば RACK_ENV, RAILS_ENV など。
+  load_path_cache:      true,                 # キャッシュで LOAD_PATH を最適化する。
+  autoload_paths_cache: true,                 # キャッシュで ActiveSupport による autoload を行う。
+  disable_trace:        true,                 # (アルファ) `RubyVM::InstructionSequence.compile_option = { trace_instruction: false }`をセットする。
+  compile_cache_iseq:   true,                 # ISeq キャッシュをコンパイルする
+  compile_cache_yaml:   true                  # YAML キャッシュをコンパイルする
+)
+```
+
+**ヒント**: `require 'bootsnap'` を `BootLib::Require.from_gem('bootsnap', 'bootsnap')` で、 [こちらのトリック](https://github.com/Shopify/bootsnap/wiki/Bootlib::Require)を使って置き換えることができます。こうすると、巨大な`$LOAD_PATH`がある場合でも、起動時間を最短化するのに役立ちます。
+
+注意: Bootsnap と [Spring](https://github.com/rails/spring) は別領域の問題を扱うツールです。Bootsnap は個々のソースファイルの読み込みを高速化します。一方で、Spring は起動されたRailsプロセスのコピーを保持して次回の起動時に起動プロセスの一部を完全にスキップします。2つのツールはうまく連携しており、どちらも新しく生成された Rails アプリケーションにデフォルトで含まれています。
+
+### 環境
+Bootsnapのすべての機能はセットアップ時の設定に従って開発、テスト、プロダクション、および他のすべての環境で有効化されます。Shopify では、この gem を問題なくすべての環境で安全に使用しています。
+
+特定の環境で機能を無効にする場合は、必要に応じて適切な ENV 変数または設定を考慮して設定を変更することをおすすめします。
+
+## 内部動作
+
+Bootsnap は、処理に時間のかかるメソッドの結果をキャッシュすることで最適化しています。これは、大きく分けて2つのカテゴリに分けられます。
+
+* [Path Pre-Scanning](#path-pre-scanning)
+    * `Kernel#require` と `Kernel#load` を `$LOAD_PATH` フルスキャンを行わないように変更します。
+    * `ActiveSupport::Dependencies.{autoloadable_module?,load_missing_constant,depend_on}` を `ActiveSupport::Dependencies.autoload_paths` のフルスキャンを行わないようにオーバーライドします。
+* [Compilation caching](#compilation-caching)
+    * Ruby バイトコードのコンパイル結果をキャッシュするためのメソッド `RubyVM::InstructionSequence.load_iseq` が実装されています。
+    * `YAML.load_file` を YAML オブジェクトのロード結果を MessagePack でキャッシュするように変更します。 MessagePack でサポートされていないタイプが使われている場合は Marshal が使われます。
+
+### Path Pre-Scanning
+
+_(このライブラリは [bootscale](https://github.com/byroot/bootscale) という別のライブラリを元に開発されました)_
+
+Bootsnap の初期化時、あるいはパス(例えば、`$LOAD_PATH`)の変更時に、`Bootsnap::LoadPathCache` がキャッシュから必要なエントリーのリストを読み込みます。または、必要に応じてフルスキャンを実行し結果をキャッシュします。
+その後、たとえば `require 'foo'` を評価する場合, Ruby は `$LOAD_PATH` `['x', 'y', ...]` のすべてのエントリーを繰り返し評価することで `x/foo.rb`, `y/foo.rb` などを探索します。これに対して Bootsnap は、キャッシュされた reuiqre 可能なファイルと `$LOAD_PATH` を見ることで、Rubyが最終的に選択するであろうパスで置き換えます。
+
+この動作によって生成された syscall を見ると、最終的な結果は以前なら次のようになります。
+
+```
+open  x/foo.rb # (fail)
+# (imagine this with 500 $LOAD_PATH entries instead of two)
+open  y/foo.rb # (success)
+close y/foo.rb
+open  y/foo.rb
+...
+```
+
+これが、次のようになります:
+
+```
+open y/foo.rb
+...
+```
+
+`autoload_paths_cache` オプションが `Bootsnap.setup` に与えられている場合、`ActiveSupport::Dependencies.autoload_paths` をトラバースする方法にはまったく同じ最適化が使用されます。
+
+`*_path_cache` を機能させるオーバーライドを図にすると、次のようになります。
+
+![Bootsnapの説明図](https://cloud.githubusercontent.com/assets/3074765/24532120/eed94e64-158b-11e7-9137-438d759b2ac8.png)
+
+Bootsnap は、 `$LOAD_PATH` エントリを安定エントリと不安定エントリの2つのカテゴリに分類します。不安定エントリはアプリケーションが起動するたびにスキャンされ、そのキャッシュは30秒間だけ有効になります。安定エントリーに期限切れはありません。コンテンツがスキャンされると、決して変更されないものとみなされます。
+
+安定していると考えられる唯一のディレクトリは、Rubyのインストールプレフィックス (`RbConfig::CONFIG['prefix']`, または `/usr/local/ruby` や `~/.rubies/x.y.z`)下にあるものと、`Gem.path` (たとえば　`~/.gem/ruby/x.y.z`) や `Bundler.bundle_path` 下にあるものです。他のすべては不安定エントリと分類されます。
+
+[`Bootsnap::LoadPathCache::Cache`](https://github.com/Shopify/bootsnap/blob/master/lib/bootsnap/load_path_cache/cache.rb) に加えて次の図では、エントリの解決がどのように機能するかを理解するのに役立つかもしれません。経路探索は以下のようになります。
+
+![パス探索の仕組み](https://cloud.githubusercontent.com/assets/3074765/25388270/670b5652-299b-11e7-87fb-975647f68981.png)
+
+また、`LoadError` のスキャンがどれほど重いかに注意を払うことも大切です。もし Ruby が `require 'something'` を評価し、そのファイルが `$LOAD_PATH` にない場合は、それを知るために `2 * $LOAD_PATH.length` のファイルシステムアスセスが必要になります。Bootsnap は、ファイルシステムにまったく触れずに `LoadError` を投げ、この結果をキャッシュします。
+
+## Compilation Caching
+
+*（このコンセプトのより分かりやすい解説は [yomikomu](https://github.com/ko1/yomikomu) をお読み下さい。)*
+
+Ruby には複雑な文法が実装されており、構文解析は簡単なオペレーションではありません。1.9以降、Ruby は Ruby ソースを内部のバイトコードに変換した後、Ruby VM によって実行してきました。2.3.0 以降、[RubyはAPIを公開し](https://ruby-doc.org/core-2.3.0/RubyVM/InstructionSequence.html)、そのバイトコードをキャッシュすることができるようになりました。これにより、同じファイルが複数ロードされた時の、比較的時間のかかる部分をバイパスすることができます。
+
+また、アプリケーションの起動時に YAML ドキュメントの読み込みに多くの時間を費やしていることを発見しました。そして、 MessagePack と Marshal は deserialization にあたって YAML よりもはるかに高速であるということに気付きました。そこで、YAML ドキュメントを、Ruby バイトコードと同じコンパイルキャッシングの最適化を施すことで、高速化しています。Ruby の "バイトコード" フォーマットに相当するものは MessagePack ドキュメント (あるいは、MessagePack をサポートしていないタイプの YAML ドキュメントの場合は、Marshal stream)になります。
+
+これらのコンパイル結果は、入力ファイル（FNV1a-64）のフルパスのハッシュを取って生成されたファイル名で、キャッシュディレクトリに保存されます。
+
+Bootsnap 無しでは、ファイルを `require` するために生成された syscall の順序は次のようになっていました:
+
+```
+open    /c/foo.rb -> m
+fstat64 m
+close   m
+open    /c/foo.rb -> o
+fstat64 o
+fstat64 o
+read    o
+read    o
+...
+close   o
+```
+
+しかし Bootsnap では、次のようになります:
+
+```
+open      /c/foo.rb -> n
+fstat64   n
+close     n
+open      /c/foo.rb -> n
+fstat64   n
+open      (cache) -> m
+read      m
+read      m
+close     m
+close     n
+```
+
+これは一見劣化していると思われるかもしれませんが、性能に大きな違いがあります。
+
+*（両方のリストの最初の3つの syscalls -- `open`, `fstat64`, `close` -- は本質的に有用ではありません。[このRubyパッチ](https://bugs.ruby-lang.org/issues/13378)は、Boosnap と組み合わせることによって、それらを最適化しています）*
+
+Bootsnap は、64バイトのヘッダーとそれに続くキャッシュの内容を含んだキャッシュファイルを書き込みます。ヘッダーは、次のいくつかのフィールドで構成されるキャッシュキーです。
+
+- `version`、Bootsnapにハードコードされる基本的なスキーマのバージョン
+- `os_version`、(macOS, BSDの) 現在のカーネルバージョンか 、(Linuxの) glibc のバージョンのハッシュ
+- `compile_option`、`RubyVM::InstructionSequence.compile_option` の返り値
+- `ruby_revision`、コンパイルされたRubyのバージョン
+- `size`、ソースファイルのサイズ
+- `mtime`、コンパイル時のソースファイルの最終変更タイムスタンプ
+- `data_size`、バッファに読み込む必要のあるヘッダーに続くバイト数。
+
+キーが有効な場合、キャッシュがファイルからロードされます。そうでない場合、キャッシュは再生成され、現在のキャッシュを破棄します。
+
+# 最終的なキャッシュ結果
+
+次のファイル構造があるとします。
+
+```
+/
+├── a
+├── b
+└── c
+    └── foo.rb
+```
+
+そして、このような `$LOAD_PATH` があるとします。
+
+```
+["/a", "/b", "/c"]
+```
+
+Bootsnap なしで `require 'foo'` を呼び出すと、Ruby は次の順序で syscalls を生成します:
+
+```
+open    /a/foo.rb -> -1
+open    /b/foo.rb -> -1
+open    /c/foo.rb -> n
+close   n
+open    /c/foo.rb -> m
+fstat64 m
+close   m
+open    /c/foo.rb -> o
+fstat64 o
+fstat64 o
+read    o
+read    o
+...
+close   o
+```
+
+しかし Bootsnap では、次のようになります:
+
+```
+open      /c/foo.rb -> n
+fstat64   n
+close     n
+open      /c/foo.rb -> n
+fstat64   n
+open      (cache) -> m
+read      m
+read      m
+close     m
+close     n
+```
+
+Bootsnap なしで `require 'nope'` を呼び出すと、次のようになります:
+
+```
+open    /a/nope.rb -> -1
+open    /b/nope.rb -> -1
+open    /c/nope.rb -> -1
+open    /a/nope.bundle -> -1
+open    /b/nope.bundle -> -1
+open    /c/nope.bundle -> -1
+```
+
+...そして、Bootsnap で `require 'nope'` を呼び出すと、次のようになります...
+
+```
+# (nothing!)
+```

data/README.md

@@ -1,7 +1,5 @@
 # Bootsnap [![Build Status](https://travis-ci.org/Shopify/bootsnap.svg?branch=master)](https://travis-ci.org/Shopify/bootsnap)
 
-**Beta-quality. See [the last section of this README](#trustworthiness).**
-
 Bootsnap is a library that plugs into Ruby, with optional support for `ActiveSupport` and `YAML`,
 to optimize and cache expensive computations. See [How Does This Work](#how-does-this-work).
 
@@ -12,21 +10,26 @@ to optimize and cache expensive computations. See [How Does This Work](#how-does
 
 ## Usage
 
-This gem works on MacOS and Linux.
+This gem works on macOS and Linux.
 
 Add `bootsnap` to your `Gemfile`:
 
 ```ruby
-gem 'bootsnap'
+gem 'bootsnap', require: false
 ```
 
-If you are using rails, add this to `config/boot.rb` immediately after `require 'bundler/setup'`:
+If you are using Rails, add this to `config/boot.rb` immediately after `require 'bundler/setup'`:
 
 ```ruby
 require 'bootsnap/setup'
 ```
 
-If you are not using rails, or if you are but want more control over things, add this to your
+It's technically possible to simply specify `gem 'bootsnap', require: 'bootsnap/setup'`, but it's
+important to load Bootsnap as early as possible to get maximum performance improvement.
+
+You can see how this require works [here](https://github.com/Shopify/bootsnap/blob/master/lib/bootsnap/setup.rb).
+
+If you are not using Rails, or if you are but want more control over things, add this to your
 application setup immediately after `require 'bundler/setup'` (i.e. as early as possible: the sooner
 this is loaded, the sooner it can start optimizing things)
 
@@ -48,6 +51,17 @@ Bootsnap.setup(
 'bootsnap')` using [this trick](https://github.com/Shopify/bootsnap/wiki/Bootlib::Require). This
 will help optimize boot time further if you have an extremely large `$LOAD_PATH`.
 
+Note: Bootsnap and [Spring](https://github.com/rails/spring) are orthogonal tools. While Bootsnap
+speeds up the loading of individual source files, Spring keeps a copy of a pre-booted Rails process
+on hand to completely skip parts of the boot process the next time it's needed. The two tools work
+well together, and are both included in a newly-generated Rails applications by default.
+
+### Environments
+
+All Bootsnap features are enabled in development, test, production, and all other environments according to the configuration in the setup. At Shopify, we use this gem safely in all environments without issue.
+
+If you would like to disable any feature for a certain environment, we suggest changing the configuration to take into account the appropriate ENV var or configuration according to your needs.
+
 ## How does this work?
 
 Bootsnap optimizes methods to cache results of expensive computations, and can be grouped
@@ -132,7 +146,7 @@ result too, raising a `LoadError` without touching the filesystem at all.
 
 Ruby has complex grammar and parsing it is not a particularly cheap operation. Since 1.9, Ruby has
 translated ruby source to an internal bytecode format, which is then executed by the Ruby VM. Since
-2.2, Ruby [exposes an API](https://ruby-doc.org/core-2.3.0/RubyVM/InstructionSequence.html) that
+2.3.0, Ruby [exposes an API](https://ruby-doc.org/core-2.3.0/RubyVM/InstructionSequence.html) that
 allows caching that bytecode. This allows us to bypass the relatively-expensive compilation step on
 subsequent loads of the same file.
 
@@ -264,21 +278,3 @@ open    /c/nope.bundle -> -1
 ```
 # (nothing!)
 ```
-
-## Trustworthiness
-
-We use the `*_path_cache` features in production and haven't experienced any issues in a long time.
-
-The `compile_cache_*` features work well for us in development on macOS. It should work on Linux,
-and we intend to deploy it in production, but we haven't yet.
-
-`disable_trace` should be completely safe, but we don't really use it because some people like to
-use tools that make use of `trace` instructions.
-
-| feature | where we're using it |
-|-|-|
-| `load_path_cache` | everywhere |
-| `autoload_path_cache` | everywhere |
-| `disable_trace` | nowhere, but it's safe unless you need tracing |
-| `compile_cache_iseq` | development, but probably safe to use everywhere |
-| `compile_cache_yaml` | development, but probably safe to use everywhere |