text:
# xref-tag

## Discontinued
While it worked for the most part on my work projects, `xref-tag` development is now discontinued,
mostly because of issues integrating with the (undocumented) scons API.

## What is xref-tags

SConstruct Tools and Builders for generating tag and cross-reference files on Linux for C and C++.

A "tag" here is the file position where a symbol (a function, class, variable, ...) is defined in
the source code. A cross-reference or reference list is the set of file positions where a symbol
is referenced (used), for example all locations where a function is called.

## Installation

Clone the repository under your `site_scons/site_tools/` directory for your project:

    cd .../projects/<octo-succotash>/
    mkdir site_scons/site_tools/
    cd site_scons/site_tools/
    git clone https://github.com/terminatorul/xref-tag.git

The main SConstruct build script `sconstruct` or `SConstruct` should be on the same level in the
directory tree with `site_scons/`, see [SCons user manual](https://scons.org/doc/production/HTML/scons-user.html#sect-environment-toolpath).
Alternatively you can use any other directory for installation and pass it on the `toolpath`
argument in the scons script when you want to load one of the tools, see [Construction
Environments](https://scons.org/doc/production/HTML/scons-man.html#construction_environments) in
SCons manual.

## Usage
In the `SConscript` you can include the tools when you create a construction environment, like

```python
    env = Environment(tools = ['default', 'xref-tag.gcc-dep', 'xref-tag.ctags', 'xref-tag.cscope' ])
```

If the tools are not installed on the default tool path, specify the install directory with an
explicit `toolpath` argument:

```python
    env = Environment(tools = ['default', 'xref-tag.gtags'], toolpath = [ xref_tag_install_dir ])
```

After creating the environment with the `xref-tag` tools, you can use the SCons Builders that are
now available to create new targets in your build script that will run `ctags`, `cscope`, `gtags`
or `cflow` commands to build tag and cross-reference files for your source code:

```python
    lib   = env.SharedLibrary('octo', [ lib-src-files... ])
    exe   = env.Program('succotash',  [ exe-src-files... ])

    ctags = env.TagsFile   ('tags',       [ lib, exe, other sources ... ])
    xref  = env.CScopeXRef ('cscope.out', [ lib, other sources ... ])
    flow  = env.CFlowTree  (              [ exe, ... ])
    gtags = env.GTAGS      ('.',          [ lib, exe, src... ])

    ccdb  = CompileCommands('compile_commands.json', [ lib, exe, ... ])

    tags  = env.Alias     ('all-tags',    [ ctags, xref, flow, gtags ])
```

These Builds and Tools were tested SCons version 3.1.1 and python 2.7.

## Included tools
- '**xref-tag.gtags**'

  Configures the build environment with variables to run
  [`gtags`](https://www.gnu.org/software/global/globaldoc_toc.html#gtags) command, from GNU GLOBAL
  source code tagging system, available from https://www.gnu.org/software/global/ and from most
  Linux distributions.

  Ex. installation for Ubuntu Linux: `apt install global`

  Tested with GNU GLOBAL 6.6.3.

  GNU global this is the most recently developed of the code browsing commands supported. It only
  supports parsing files inside the current project directory. To allow indexing of any sources
  and `#include`s outside the project, this tool will run the `gtags` command by default in the
  root directory of the file system, but will use the proper options on the command line to
  keep the resulting files in the project directory. Searching for a tag with GNU global will
  still show results relative to the current directory. To change this behavior and see
  the other options, check Variables List bellow.

  Builder:
    - gtags = **GTAGS**('dbpath/', [ targets... ])

      The `dbpath/` is the directory where the tag and reference files `GTAGS`, `GRTAGS`, `GPATH`
      and `GTAGSROOT` will be generated. Optional, the default will be set to the local
      `SConscript` directory (`Dir('.').srcnode()`) at the time the environment is created.

      All source files used to build the given targets will be enumerated and passed to the
      `gtags` command, with all known dependency `#include`s. You can also pass source files
      directly instead of the targets, but scanning for nested `#include`s will be limited, as
      the file is never compiled, so this is not recommended.

      To guarantee all dependency `#include`s are known, including system headers, add
      '**xref-tag.gcc-dep**' tool to the build environment, It will append `gcc` and
      `g++` options to list `#include` dependencies when source files are compiled, see
      bellow. With this mechanism however you will need to run tag generation a second time
      after the first build, and after `#include` line changes in a source file, see [ParseDepends()](https://scons.org/doc/production/HTML/scons-user.html#idm1236)
      function in SCons user manual.

      After tag and reference files are generated, you can use
      [`global`](https://www.gnu.org/software/global/globaldoc_toc.html#global) or
      [`gtags-cscope`](https://www.gnu.org/software/global/globaldoc_toc.html#gtags_002dcscope)
      commands to query for symbol definition or uses, or integrate with an editor (like gVim)
      or IDE for this purpose.

      If you use [`gtags-cscope`](https://www.gnu.org/software/global/globaldoc_toc.html#gtags_002dcscope),
      beware it will try to update the resulting tag and reference files automatically,
      but without the same options on the command line that SCons is using. This means you should
      have a `gtags.conf` or `~/.globalrc` file with the same configuration provided by SCons
      (see GTAGSCONFIG below in [Tool Variables](#tool-variables)). Otherwise, C++ system headers
      with no extension (like `<iostream>`) will be re-considered plain text files, and no C++ symbols
      will be visible. Or you can always use `-d` option on `gtags-cscope` command line, to disable the
      automatic update of the reference files.

      For [Vim](https://www.vim.org/) integration you can use either of:
	- `gtags.vim` plugin file provided with GNU GLOBAL. Create a symlink to `/usr/local/share/gtags/gtags.vim`
	  under your [Vim](https://www.vim.org/) plugins directory, and then use the `:Gtags` command,
	  see the documentation on [Vim using GLOBAL](https://www.gnu.org/software/global/globaldoc_toc.html#Vim-editor).
	- `:set cscopeprg=gtags-cscope\ -d`, see [cscopeprg](https://vimhelp.org/if_cscop.txt.html#cscopeprg)
	  option in Vim [cscope interface](https://vimhelp.org/if_cscop.txt.html) and
	  [Gtags-cscope](https://www.gnu.org/software/global/globaldoc_toc.html#Gtags_002dcscope) section.
	  Afterwards you can use `:cscope add GTAGS` command to add a database.

- '**xref-tag.cscope**'

  Configures the build environment with variables to run `cscope` command, available from http://cscope.sourceforge.net/
  and from most Linux distributions.

    Ex. installation for Ubuntu Linux: `apt install cscope`

  Tested with cscope version 15.8b.

  According to the documentation `cscope` command is meant to reference and navigate `C` source
  code, but it is known to still work with `C++` for most uses, so this tool will pass `C++`
  source file to the command.

  Builders:
    - xref = **CScopeXRef**('xref-file', [ targets... ])

      The `xref-file` will be generated with `cscope` command, with references to symbols in the
      source files. Passing the `xref-file` is optional, if not given the default will is
      `cscope.out` in the local `SConscript` directory. An additional `namefile` will
      be created in the same directory named `cscope.files` by default, holding list of
      files used to generate the `xref-file`. This file is later needed by `cscope` and is used to
      keep the `xref-file` up-to-date next on each `cscope` invocation. But in order to detect
      changes to `#include` directories, it is recommended to use SConstruct to update the
      `xref-file`. If using another name for the `namefile` (not the default of `cscope.files`),
      you should use the `-f` flag to `cscope` whenever you invoke it, interactively or in
      single-query (command line) mode.

      Two more files, `cscope.out.in` and `csope.out.po` are placed in the same directory as
      `cscope.out`, to hold an additional inverted index that will speed up symbol look-ups.

      Source dependencies for given `targets...` will be enumerated and passed to the
      `cscope`. You can give source files as `targets...`, but scanning for nested `#include`s
      will not be the same, as the file is not compiled, so you should avoid this usage when possible.

      To ensure all dependency `#include`s are known, including  system headers, load the
      '**xref-tag.gcc-dep**' tool (see bellow) in the build environment. It will append
      `gcc` and `g++` options to output the list of `#include`s when
      source files are compiled. With this mechanism however you will need to run tag
      generation a second time after the first build and after any `#include` line changes in a
      source file, see [ParseDepends()](https://scons.org/doc/production/HTML/scons-user.html#idm1236)
      function in SCons user manual for this issue.

      After the cross-reference fils is generated, use `cscope` command in the same
      directory to find symbols and references.
      `cscope` command will update the cross-reference file before before use. But if you
      move things around in your project and change the include directories, or you add new source
      files, `cscope` will not know about it untill your regenerate the `xref-file` with SCons. Some
      editors integrate with `cscope` to get access to the refrences for navigation while editing.
      For [Vim](https://www.vim.org) integration see [cscope interface](https://vimhelp.org/if_cscop.txt.html)
      and [Vim/Cscope tutorial](http://cscope.sourceforge.net/cscope_vim_tutorial.html).

      The `cscope` command works both in an interactive terminal with a Text
      User Interface (TUI), or in the good old command line mode with the `-L` and `-0` .. `-9` options.

      If you split your project into subprojects, with their own `cscope.out` files, an editor like
      `Vim` will be able to load them all. See [Vim support](#vim-support-function) section below
      for a Vim function and key mapping for loading `cscope.out` and `cscope.lib.out` files found
      under the current directory (up to 4 levels deep by default).

    - xref = **CScopeDirXRef**('xref-file', [ libdir... ])

      `cscope` has two modes of operation: file-list mode and directory-scanning mode.
      `CScopeXRef()` builder uses file-list mode, based on a `namefile` with an explicit list of
      file names, and `CScopeDirXRef()` builder uses directory-scanning mode.
      The directory scanning mode is not flexible enough for most use cases and it is recommended to
      use `CScopeXRef()` instead when possible.

      In directory mode `cscope` will scan for `C`, `yacc` and `lex` and `C++` source files in the following
      directories:
	    - current (build) directory
	    - directories passed to `CScopeDirXRef()`
	    - directories from `SOURCEDIRS` variable in the execution environment `env['ENV']`.

      Recurse subdirectories `-R` flag to `cscope` can be usefull in this mode (not used by default).

      `cscope` also uses `INCLUDEDIRS` variable in the execution environment will be used to search for included
      files.

      The cross-reference database will be generated with symbols from the files found.

- '**xref-tag.ctags**'

   Configures the build environment with variables to run `ctags` command, either one of:
    - exuberant-ctags: http://ctags.sourceforge.net/
    - universal-ctags: https://ctags.io/

   `ctags` command is available from most Linux distributions.

   Ex. installation for Ubuntu Linux: `apt install exuberant-ctags`

   Tested with Exuberant ctags 5.9.

   This command can only generate a tags file and locate symbol definitions, with no
   cross-references, so there is no option to search for all uses of a function or variable.

   However `catgs` can parse a large list of languages and is generally a more reliable tool
   at what it does, because parsing C++ code for references is complex and is normally not
   implemented properly in various tools.

   Another detail is that `ctags` implements no incremental update. Although scanning is fast
   anyway, so it is only a problem for large projects that already have larger build times.
   And it is possible to simulate an incremental update by properly manipulating the tags
   file before running `ctags`.

   Builder:
    - ctags = **TagsFile**('tags', [ target... ])

      `ctags` command will generate the given `'tags'` file with symbol definitions. The `'tags'`
      file is optional, the default will be `'tags'` in the local `SConscript` directory (at
      the time environment is created).

      All source dependencies for the given `targets...` will be enumerated and passed to
      `ctags` for scanning and tags generation. You can give source files as
      `targets...`, but scanning for nested `#include`s will be limited, as the file is not
      compiled, so doing so is not recommended.

      To ensure all dependecy `#includes`s are parsed, use **xref-tag.gcc-dep** tool (see
      bellow) in the build environment. This will append `gcc` and `g++` command
      options to output the list of `#include` dependencies when source files are
      compiled. With this mechanism however you will need to run tag generation a second
      time after the first build and after any `#include` line changes in a source file, see
      [ParseDepends()](https://scons.org/doc/production/HTML/scons-user.html#idm1236)
      function in SCons user manual for this issue.

      After the `tag` file is generated, it can be used in editors / IDEs that integrate tag
      files for navigationn while editing. The file format is text-based and rather simple,
      so there are tools that can generate and use a `tag` file for many languages. For
      [Vim](https://www.vim.org) integration see [Moving through programs](https://vimhelp.org/usr_29.txt.html#usr_29.txt)
      and [Tags and special searches](https://vimhelp.org/tagsrch.txt.html) in the documentation.

      On the command line you can open the location of a tag using Linux `less` command in a
      terminal, with `-t` argument for the tag to locate, and `-T` for the tag file if
      non-default. Use `t` and `T` keys with `less` to navigate to the next and previous tag
      locations.

      If you split your project into subprojects with their own `tags` file, [Vim](https://www.vim.org)
      will be able to load all the tag files by setting the '[tags](https://vimhelp.org/tagsrch.txt.html#tags-option)'
      option. '[tagrelative](https://vimhelp.org/tagsrch.txt.html#tagrelative-option)' option
      should also be set, unless you build all tag files from the same directory. See
      [Vim support](#vim-support) section below for a function to search and load all tag
      files under the current directory up to 4 levels deep by default.

- '**xref-tag.cflow**'

    Configures the build environment with variables for running `cflow` command, available at:
	- https://www.gnu.org/software/cflow/

    Ex. installation for Ubuntu Linux: `sudo apt install cflow`

    Tested only somewhat successfully with GNU cflow 1.6 as it looks it can not successfully
    parse all system headers.

    The command works with 'C' sources, and will output a direct and reverse call tree over the
    entire set of sources.  Will also output a third format which is a cross-references of uses
    (calls) and definitions for functions, in line-oriented text format.

    Unfortunately unreliable in my experience, the command has options to parse pre-processed
    source for better visibility into the definitions and syntax, but I struggled to get it to
    work at all while developing the SConstruct integration, so now it works in no-preprocessing
    mode. It produces a listing of every function call, presented in a tree with indentation or
    ASCII art.

    Builder:
     - cflow = **CFlowTree**('calltree.cflow', [ targets... ])

       Will output 3 files related to the call tree of the given target:
	    - a direct call tree, with the default extension `.cflow`
	    - a reverse call tree, with extension `.reverse.cflow`
	    - a listing referencing all function calls found, with extension `.xref.cflow`

       All sources for the given `targets...` will be enumerated and passed to the `cflow` command
       line. You can also pass source files as the `targets...`, and they will be included in
       the `ctags` command line.

       It is still recommended to load the '**xref-tag.gcc-dep**' tool to guarantee the correct
       list of `#include` dependencies is found. With this mechanism however you will need to run
       tag generation a second time after the first build and after any `#include` line changes
       in a source file, see [ParseDepends()](https://scons.org/doc/production/HTML/scons-user.html#idm1236)
       function in SCons user manual for this issue.

       After generating the call graph, it can be immediately inspected as it is a text file
       with proper indentation and possibly showing an ASCII tree if the options are included.

- '**xref-tag.cccom**'

    Write a JSON Compilation Database file (with `C`/`C++` compile commands), as specified in:
	- https://clang.llvm.org/docs/JSONCompilationDatabase.html

    This file is a listing with the compilation command line of each translation unit in a target binary.
    It is meant as input for code parsing tools based on `clang`, that need access to compilation options,
    like include directories and macro definitions, for each source file, to ensure accurate scanning.

    The generated file can be used for running [RTags](https://github.com/Andersbakken/rtags) or
    [clang-tags](https://github.com/ffevotte/clang-tags) commands to generate tag and cross-reference
    caches.

    Beware your project must compile successfully with `clang` compiler in this case. Even if
    clang is only parsing sources, errors may still stop it from completing the parse. If you compile
    [RTags](https://github.com/Andersbakken/rtags) or [clang-tags](https://github.com/ffevotte/clang-tags)
    from sources, which is the current installation procedure, you should use a newer version of
    `libclang` like `6.0`.

    For these uses, you should have the system include directories in `CFLAGS` and `CXXFLAGS`
    construction vairables (introduced with `-isystem` command line flag), and you should also add `clang`
    command line option `-ferror-limit=0`, so `clang` will continue parsing after any number of errors.
    See [Tool Variables](#tool-variables) section below for the options to alter the build environment
    for the generated compile commands.

    If using [RTags](https://github.com/Andersbakken/rtags), it already adds `-ferror-limit=50` option to
    `clang`, and offers a command-line flag to query the compiler for system include directories.

    Builder:
     - ccdb = **CompileCommands**('compile_commands.json', [ targets... ])

    The `[ target... ]` list, which gives the sources to this builder, contains other executables and
    libraries built in the same SCons project. Source files for this binaries will be included in the
    generated compile commands. Only `C` and `C++` sources are listed by default. The name for the
    generated file is optional, if needed the default value `compile_commands.json` will be used.

    `CompilationDatabase()` is an alias for `CompileCommands()`.

    When using [`VariantDir(duplicate = True)`](https://scons.org/doc/production/HTML/scons-man.html#f-VariantDir),
    , generated compile commands will be altered so compilation appears to use original sources from
    the local `SConscript` directory, instead of duplicated sources in the variant directory. If you
    want to disable this and keep the build commands accurate, set `CCCOM_KEEP_VARIANT_DIR` to `True`.

- '**xref-tag.gcc-dep**'

    Configures `gcc` and `g++` command line options in the given build environment for listing
    the complete list of `#include` file dependencies during compilation. This ensures that
    no source file will be missing from the generated tags, but also means the additional dependency
    files are loaded every time `scons` runs.

    There are no Builders exposed by `'xref-tag.gcc-dep'`. It must be loaded _after_ `gcc` and `g++`,
    and will automatically inject:

	- options to generate a dependecy file (`*.d`) next to the object file at compile time:
	- loading previous generated dependency files whenever `scons` starts
	- loading re-generated dependency files again after a compilation
	- adding the dependency file to the build system so they are added to the targets to
	  be cleaned

- '**xref-tag.gcc-cpp**'

    Configures `gcc` and `g++` command line options in the given environement, for listing the
    preprocessed output and the assembly listing file during compilation, and keeping the files
    for later. This tool must be loaded *after* `gcc` and `g++` are loaded, and it will:
	- add `-save-temps=obj` option to `gcc` command line to save the preprocessed and assembly
	  files during compilation
	- automatically add the new files as side-effects of building the new object files, and
	  add them as dependencies to be cleaned when cleaning the object file target

    This module is not currently used and will waste a lot of disk space, however in general
    there is some value in the preprocessed source for the source code cross-reference commands,
    for example `ctags` has an option for following `#line` directives in preprocessed sources.

## Tool variables:

 - '**xref-tag.gtags**'
    - `$GTAGS`
	    - `gtags` command name, default `gtags`
    - `$GTAGSDBPATH`
	    - default destination directory for the `dbpath/`, default is the local `SConscript`
	      directory
    - `$GTAGSFLAGS`
	    - command line options for `gtags` command, default `[ '--statistics' ]`
    - `$GTAGSSTDINFLAG`
	    - list of flags needed for nested `gtags` process to have the process read the list of
	      files from standard input, default `[ '-f', '-' ]`
    - `$GTAGSCONFIGFLAG`
	    - list of `gtags` command line flags for selecting a confguration file, default
		`[ '--gtagsconf' ]`
    - `$GTAGSOUTPUTFLAG`
	    - list of `gtags` command options for selecting the output files (`GTAGS`, `GRTAGS` and
	      `GPATH`). Default empty `[ ]`, as `gtags` has no such options.
    - `$GTAGSOUTPUTS`
	    - files that will be output by `gtags` after generating the tags in the `dbpath`
	       directory. Default `[ 'GTAGS', 'GRTAGS', 'GPATH' , 'GTAGSROOT' ]`, except the last
	       output file `GTAGSROOT` is generated by the `'xref-tag.gtags'` tool at buiild time
	       from the `$GITASROOT` variable, if seet
    - `$GTAGSROOT`
	    - common root directoy for all the files in the project, including system headers that
	      may be loaded by `xref-tag.gcc-dep` tool. Files outside this directory will be
	      ignored by `gtags` even if given as input for tag file generation. The value of this
	      variable is written at build time in the `GTAGSROOT` file in `dbpath`. Default is
	      the filesystem root `/`.
    - `$GTAGSADDENV`
	    - dictionary with environment variables to be passed to the `gtags` subprocess for
	      tag generation. Default `{ 'GTAGSFORCECPP': 1 }` to allow parsing `.h` files as
	      `C++` instead of the default language `C`
    - `$GTAGSCONFIGLIST`
	    - list of config files, searched and loaded by `gtags` command by default. Only used
	      as additional dependencies to the resulting tag and reference files, as they should
	      be re-generated when the tool configuration changes for example the language map.

	      The option is only used when `$GTAGSCONFIG` is not given, as otherwise that value
	      takes precedence over the other config files.

	      Default `[ '/usr/local/etc/gtags.conf', '/etc/gtags.conf', os.path.join(os.environ['HOME'], '.globalrc'), '/gtags.conf' ]`
    - `$GTAGSCONFIG`
	    - `gtags` config file contents as a python list with lines of text. Written to a temporary file
	       at build time, with the temporary file name passed to `gtags` as the config file.
	       Default is:

		```python
                [
                    'default:\\',
                    '   :langmap=c\\:.c.h,yacc\\:.y,asm\\:.s.S,java\\:.java,cpp\\:.c++.cc.hh.cpp.cxx.hxx.hpp.C.H.tcc,php\\:.php.php3.phtml,cpp\\:(*):'
                ]
		```
		which is the `gtags` default language map, modified to allow parsing files without
		extension, like `<iostream>`, and files with `.tcc` extension, as `C++` sources
    - `$GTAGSSUFFIXES`
	    - list with suffixes for files that can be parsed by `gtags`. Any files with a
	      non-matching extension will not be included as input to the `gtags` command.
	      Default is:

	      ```python
                [
                    '.c', '.h',
                    '.y',
                    '.s', '.S',
                    '.java',
                    '.c++', '.cc', '.hh', '.cpp', '.cxx', '.hxx', '.hpp', '.C', '.H', '.tcc', '',
                    '.php', '.php3', '.phtml'
                ]
	      ```
	      Extensions `.tcc` and `` above were added here to support parsing system header files
	      for GNU compilers.
 - '**xref-tag.cscope**'
    - `$CSCOPE`
	    - `cscope` command name, default `cscope`
    - `$CSCOPEQUICKFLAG`
	    - list of `cscope` flags to build a second inverted index for fast symbol look-ups.
	      The options is included in the default value for `$CSCOPEFLAGS`, and when
	      detected there will add the second index files as additional targets output from
	      the builder for `cscope` command. Default `[ '-q' ]`
    - `$CSCOPEFLAGS`
	    - list of command line flags to be passed to `cscope` command. Default
	      `[ '-b', '-q', '-k' ]` (build cross-reference, build quick-index and ignore system
	      (default) include directories)
    - `$CSCOPEINCFLAG`
	    - list of flags for passing an include directory to `cscope` command line, default
	      `[ '-I' ]`
    - `$CSCOPEPATH`
	    - list of include directories passed to `cscope` command. Each one will be preceded
	      on the resulting command line by the value of `$CSCOPEINCFLAG`. Default `$CPPPATH`.
    - `$CSCOPESYSPATH`
	    - list of system include directories, that are not normally listed on the compiler
	      command line or in `$CPPPATH`. Normally used together with the `-k` option to
	      disable automatic searching of the system include directories by `cscope`. To find
	      system include directories for GNU compilers, preprocess an empty source file with
	      the `-v` preprocessor flag. You can use `/dev/null` file and explicitly
	      specify the source language as `c` or `c++` with the `-x` option, like this:
	      ```
                 gcc -E -Wp,-v -xc   /dev/null
                 g++ -E -Wp,-v -xc++ /dev/null
	      ```
    - `$CSCOPEDIRECTORY`
	    - the directory to run `cscope` in. This is significant for the resulting
	      cross-reference file and should be the directory that you will be using `cscope`
	      from, for example the current directory in the source editor used for
	      code browsing. Default is the current source directory, given as
	      `env.Dir('.').srcnode()`.
    - `$CSCOPESTDINFLAGS`
	    - list of `cscope` flags to request reading list of input files from standard input.
	      Used at build time to feed the running `cscope` process the list of input files,
	      one per line. Files with spaces are included in double quotes, and existing
	      double quotes and back slashes in the file name are escaped with a backslash
    - `$CSCOPEOUTPUTFLAG`
	    - list fo `cscope` flags to give the main cross-reference file name. The inverted
	      index files are named after this file with the .in and .out extensions added
    - `$CSCOPEOUTPUTFILE`
	    - default target name (xref-file), when the builder is called with only the source
	      nodes and no target node. The default is `cscope.out` in the local `SConscript`
	      directory `env.File('cscope.out').srcnode()`
    - `$CSCOPENAMEFILE`
	    - default name for the `cscope` 'namefile'. The list of input files to `cscope`
	      process is written in this file. Needed by `cscope` at a later time and
	      used to keep the xref file up-to-date. This file will include the options present
	      both on the command line and in `$CSCOPENAMEFILEFLAGS` bellow, and the include
	      directories from command line in case the same variable allows the `$CSCOPEINCFLAGS`
	      option.
    - `$CSCOPENAMEFILEFLAGS`
	    - list of flags from the command line that should be saved at the beginging of the
	      generated namefile. Default `[ '-I', '-c', '-k', '-p', '-q', '-T' ]`.
    - `$CSCOPESUFFIXES`
	    - python list with files suffixes that can be parsed by `cscope`. Non-matching source
	      files are filtered out and are not source nodes for the target xref file.
	      Default C and C++:
	      ``` python
                [
                    '',
                    '.c', '.y',
                    '.i', '.c++', '.cc', '.cp', '.cpp', '.cxx',
                    '.h', '.h++', '.hh', '.hp', '.hpp', '.hxx', '.C', '.H', '.tcc'
                ]
	      ```

- '**xref-tag.ctags**'
    - `$CTAGS`
	    - `ctags` command name, default `ctags`
    - `$CTAGSFLAGS`
	    - list command line flags to be passed to `ctags`. Default value:

             ```python
                [
                    '-h', '+.',
                    '--c-kinds=+px',
                    '--c++-kinds=+px',
                    '--extra=+q',
                    '--langmap=c++:+.tcc.',
                    '--fields=+iaSt',
                    '--totals=yes'
                ]
             ```

	     allows for a richer resulting tags file and for parsing files without an extension, like
	     `<iostream>`, plus files with `.tcc` extension, as `C++`
    - `$CTAGSDEFPREFIX`
	    - list of options to introduce a definition on `ctags` command line (similar to the compiler
	      definitions). Default `[ '-I' ]`
    - `$CTAGSSTDINFLAGS`
	    - list of `ctags` options for reading list of input files from the standard input stream
	      of the process. Default `[ '-L', '-' ]`
    - `$CTAGSOUTPUTFLAG`
	    - list of `ctags` flags to give the output file name (tags file name). Default `[ '-o' ]`
    - `$CTAGSDEF`
	    - list of macro definitions to be passed to `ctags` command line. Each of them will be
	      preceeded on the command line by the flags in `$CTAGSDEFPREFIX`. Default value includes
	      some macro replacements to allow `ctags` to parse system headers for GNU compilers:

	      ```python
                [
                    '_GLIBCXX_NOEXCEPT',
                    '_GLIBCXX_VISIBILITY+',
                    '_GLIBCXX_VISIBILITY(x)'
                ]
	      ```
    - `$CTAGSFILE`
	    - default name for the output file where tags are generated (the tags file). Used when the
	      builder is invoked with the source argument only, and no target argument. Default is the `#tags`
	      file in the top level SConstruct source directory
    - `$CTAGSCONFIG`
	    - python list with config files searched and loaded by default by `ctags`. Only used as
	      additional dependencies for the resulting tags file, so tags will be regenerated when
	      config file changes. Default value:

	      ```python
                [
                    '/etc/ctags.conf',
                    '/usr/local/etc/ctags.conf',
                    os.path.join(os.environ['HOME'], '.ctags'),
                    '#.ctags'
                ]
	      ```
    - `$CTAGSSUFFIXES`
	    - python list with suffixes for files `ctags` can parse. Only matching files will the given
	      to `ctags` command, others are discarded. Default:

	      ```python
	      [
                    '',
                    '.build.xml',
                    '.asm', '.ASM', '.s', '.S', '.A51', '.29k', '.29K', # *.[68][68][kKsSxX] *.[xX][68][68]
                    '.asp', '.asa',
                    '.awk', '.gawk', '.mawk',
                    '.bas', '.bi', '.bb', '.pb',
                    '.bet',
                    '.c',
                    '.c++', '.cc', '.cp', '.cpp', '.cxx',
                    '.h', '.h++', '.hh', '.hp', '.hpp', '.hxx', '.C', '.H', '.tcc',
                    '.cs',
                    '.cbl', '.cob', '.CBL', '.COB',
                    '.bat', '.cmd',
                    '.e',
                    '.erl', '.ERL', '.hrl', '.HRL',
                    '.as', '.mxml',
                    '.f', '.for', '.ftn', '.f77', '.f90', '.f95',
                    '.F', '.FOR', '.FTN', '.F77', '.F90', '.F95',
                    '.go',
                    '.htm', '.html',
                    '.java',
                    '.js',
                    '.cl', '.clisp', '.el', '.l', '.lisp', '.lsp',
                    '.lua',
                    '.mak', '.mk', # [Mm]akefile GNUmakefile',
                    '.m',
                    '.m', '.h',
                    '.ml', '.mli',
                    '.p', '.pas',
                    '.pl', '.pm', '.plx', '.perl',
                    '.php', '.php3', '.phtml',
                    '.py', '.pyx', '.pxd', '.pxi', '.scons',
                    '.cmd', '.rexx', '.rx',
                    '.rb', '.ruby',
                    '.SCM', '.SM', '.sch', '.scheme', '.scm', '.sm',
                    '.sh', '.SH', '.bsh', '.bash', '.ksh', '.zsh',
                    '.sl',
                    '.sml', '.sig',
                    '.sql',
                    '.tcl', '.tk', '.wish', '.itcl',
                    '.tex',
                    '.vr', '.vri', '.vrh',
                    '.v',
                    '.vhdl', '.vhd',
                    '.vim',
                    '.y'
              ]
	      ```
- '**xref-tag.cflow**'
    - `$CFLOW`
	    - `cflow` command name, default `cflow`
    - `$CFLOWOUTPUTFLAG`
	    - list of `cflow` options for passing the output file name, default `[ '--output' ]`
    - `$CFLOWFLAGS`
	    - list of other flags to the `cflow` command, default `[ '--all', '--omit-symbol-name' ]`
    - `$CFLOWCONFIG`
	    - list of configuration files searched and loaded by `cflow` command. Only used as
	      additional dependencies for the result call graph files, so the are regenerated when
	      `cflow` configuration changes. Default `[ os.path.join(os.environ['HOME'], `.cflowrc') ]`
    - `$CFLOWPATHFLAG`
	    - list of `cflow` options for passing an include directory, to be used for pre-processing
	      Default `[ '-I' ]`
    - `$CFLOWPATH`
	    - list of include directories to be passed to `cflow` for pre-processing. Each of them
	      will be preceeded on the command line by the options from `$CFLOWPATHFLAG`. Default
	      empty.
    - `$CFLOWDEFFLAG`
	    - `cflow` options for giving a macro definitions, to be used for pre-processing.
	      Default `[ '-D' ]`
    - `$CFLOWDEF`
	    - list of macro definitions given to `cflow` command for pre-processing. Each of them
	      will be preceeded by the options in `$CFLOWDEFFLAG`. Default empty
    - `$CFLOWFORMAT`
	    - python map form a nested file extension string to a cflow output format flag.
	      `cflow` command will be run once for each extension string found, with the associated
	      output format options. Default:

	      ```python
                 {
                    '':         [ ],
                    '.reverse': [ '--reverse' ],
                    '.xref':    [ '--xref' ]
                 }
	      ```
	      The `.cflow` file extension is appended by default after the nested extensions given
	      here.
    - `$CFLOWSYMFLAG`
	    - `cflow` options for giving a symbol on the command line, default `[ '--symbol' ]`
    - `$CFLOWSYM`
	    - list of symbols (name=type) to be given to `cflow` command to fix input files parsgin
	      Default value:

	      ```python
                [
                    '__inline:=inline',
                    '__inline__:=inline',
                    '__gnu_inline__:=inline',
                    '__always_inline__:=inline',
                    '__const__:=const',
                    '__const:=const',
                    '__restrict:=',
                    '__extension__:qualifier',
                    '__attribute__:wrapper',
                    '__asm__:wrapper',
                    '__nonnull:wrapper',
                    '__nonnull__:wrapper',
                    '__wur:wrapper',
                    '__nonnull__:wrapper',
                    '__artificial__:qualifier',
                    '__leaf__:qualifier',
                    '__nothrow__:qualifier',
                    '__artificial__:qualifier',
                    '__pure__:qualifier',
                    '__asm__:qualifier'
                ]
	      ```
    - `$CFLOWCPP`
	    - list of `cflow` options to request pre-processing input file before parsing and generating
	      the call graph. Currently `cflow` command is likely to break when parsing pre-processed
	      system header files, so doing so is not recommended. Default empty `[ ]`
    - `$CFLOWSUFFIXES`
	    - list of suffixes for files that `cflow` can parse and understand. Only matching source files
	      are given as input to the command. Default 'C' and 'C++':
	      ```python
                 [
                     '.c', '.y',
                     '','.c++', '.cc', '.cp', '.cpp', '.cxx', '.h', '.h++', '.hh', '.hp', '.hpp', '.hxx', '.C', '.H'
                 ]
	      ```

- '**xref-tag.cccom**'

    - `$CCCOM_OBJPREFIX`, `$CCCOM_OBJSUFFIX`, `$CCCOM_SHOBJPREFIX`, `$CCCOM_SHOBJSUFFIX`
	    - suffixes and prefixes used to identify static and shared object dependencies for the  binary
	      targets. The defaults are the platform-provided variables `$OBJPREFIX`, `$OBJSUFFIX`,
	      `$SHOBJPREFIX`, `$SHOBJSUFFIX`.

    - `$CCCOM_SUFFIXES`
	    - List with suffixes of source files to be included in the generated commands list. Default is
	      the `C` and `C++` extensions list documented by `SCons` for the `cc` and `cxx` tools:

	      ```python
                 [ '.c', '.m', '.C', '.cc', '.cpp', '.cxx', '.c++', '.C++', '.mm' ]
	      ```

    - `CCCOM_COMMANDVAR`
	    - Strings to be expanded for each type of source file, in order to re-create the static object
	      compilation command. These are given as a list of mappings from a file suffix (extension) to the
	      string:

	      ```python
                 [
                    { '.c':   '$CCCOM'  }, { '.m':   '$CCCOM'  },
                    { '.C':   '$CXXCOM' }, { '.cc':  '$CXXCOM' }, { '.cpp': '$CXXCOM' },
                    { '.cxx': '$CXXCOM' }, { '.c++': '$CXXCOM' }, { '.C++': '$CXXCOM' },
                    { '.mm':  '$CXXCOM' }
                 ]
	      ```
            The default value above matches `SCons` documentation for `C` and `C++` builder file extensions,
            and the command string environment variables.

    - `CCCOM_SHCOMMANDVAR`
	    - Strings to be expanded for each type of source file, in order to re-create the shared object
	      compilation command. These are given as a list of mappings from a file suffix (extension) to the
	      string:
	      ```python
                 [
                     { '.c':   '$SHCCCOM'  }, { '.m':   '$SHCCCOM'  },
                     { '.C':   '$SHCXXCOM' }, { '.cc':  '$SHCXXCOM' }, { '.cpp': '$SHCXXCOM' },
                     { '.cxx': '$SHCXXCOM' }, { '.c++': '$SHCXXCOM' }, { '.C++': '$SHCXXCOM' },
                     { '.mm':  '$SHCXXCOM' }
                 ]
	      ```
            The default value above matches `SCons` documentation for `C` and `C++` builder file extensions,
            and the command string environment variables.
    - `CCCOM_DATABASE_FILE`
	    - Default file name for the compilation database, if not specified when the builder is called.
	      Default value is `compile_commands.json`.

    - `CCCOM_KEEP_VARIANT_DIR`
	    - Used to prevent name translation for duplicate source files from the
	      [VariantDir()](https://scons.org/doc/production/HTML/scons-man.html#f-VariantDir) build directory
	      to the local `SConscript` directory. Default is `False`, meaning the names will be translated, so
	      only original sources show up in the generated compile commands.

    - `CCCOM_APPEND_FLAGS`
	    - list with dictionaries mapping variable names to their content flags to be appended to the build
	      environment of each source file. This applies on a copy of the original build environment, so it
	      only affects the generated compilation database, not the actual compilation.  It allows you to
	      add extra flags to any build variables like `CFLAGS`, `CCFLAGS` and `CXXFLAGS`, and they will be
	      included in the generated compile commands. The given variable must be a list or it will be split
	      with [`env.Split`](https://scons.org/doc/production/HTML/scons-man.html#f-Split). Default is the
	      empty list `[ ]`.

	      Ex.:
	      ```python
                 CCCOM_APPEND_FLAGS = [ { 'CCFLAGS': [ '-ferror-limit=0' ] } ]
	      ```

	      `CCCOM_APPEND_FLAGS` has precedence over `CCCOM_REMOVE_FLAGS`, this way you can replace multiple
	      occurrences of the same flag with a single one, by including it in both variables.

    - `CCCOM_REMOVE_FLAGS`
	    - list with dictionaries of variable names and their content flags to be removed (filtered out)
	      from the build environment of each source file, before the compile command is generated. This
	      applies on a copy of the original build environment, so it only affects the generated compile
	      commands, not the actual compilation.
	      This allows you to remove compile flags from and build variables like `CFLAGS`, `CCFLAGS`, and
	      `CXXFLAGS`, and they will no longer show up in the generated compile commands. The given
	      variable must be a list or it will be split with [`env.Split`](https://scons.org/doc/production/HTML/scons-man.html#f-Split).
	      Default is the empty list `[ ]`.

	      Ex.:
	      ```python
                 CCCOM_REMOVE_FLAGS = [ { 'CCFLAGS': [ '-fmax-errors=0' ] } ]
	      ```

    - `CCCOM_FILTER_FUNC`
	    - Variable that will be substituted for each source file in the associated build environment.
	      Should be a user function with the following arguments:
	      ```
               target, source, env, for_signature
	      ```
	      It can alter the provided build environment `env` in any way necessary, before the compile
	      commands are generated. The substitution result should be a `True` value to include the
	      source file in the generated compile commands, and a `False` value to exclude it.

	      The construction environment for the `CompileCommands()` builder can be found as the
	      `CCCOM_ENV` variable of the build environment.

	      By default the variable is missing from the construction environment, which means all source
	      files are listed in the generated compile commands. So behavior is as if the default value is
	      `True`, or, to be complete, rather: `lambda target, source, env, for_signature: True`.

    - `CCCOM_ABSOLUTE_FILE`
	    - [JSON Compilation Database](https://clang.llvm.org/docs/JSONCompilationDatabase.html)
	      specification allows the source file name field `file` to be either a relative or an absolute
	      path. The default for `CompileCommands()` builder is a relative path. You can set this variable
	      to `True` to generate absolute source file paths.

- '**xref-tag.gcc-dep**'

    - `$GCCDEP_FLAGS`
	    - list of `gcc` and `g++` flags to generate make dependency rule files for `#include`d files,
	      during compilation. Default `[  ]`
	      ```python
                 [
                     '-MD',
                     '-MF', '${TARGET}${GCCDEP_SUFFIX}',
                     '-MT', '${TARGET.srcdir}/${TARGET.name}'
                 ]
	      ```

    - `$GCCDEP_SUFFIX`
	    - suffix for the generated make dependency rules files, default `'.d'`

    - `$GCCDEP_SUFFIXES`
	    - list of file suffixes for which the compiler can generate make dependency rules.
	      Default: `[ '.c', '.cc', '.cpp', '.cxx', '.c++', '.C++', '.C' ]`

    - `$GCCDEP_INJECTED`
	    - set to `True` when the tools was imported in the environment. Used to check if this tool
	      is already available in a given environment

- '**xref-tag.gcc-cpp**'

    - `$GCCCPP_FLAGS`
	    - list of `gcc` and `g++` flags to generate and keep pre-processed source during compilation

    - `$GCCCPP_SUFIX`
	    - list of suffixes of files output by the compiler with the proper command line options for
	      saving preprocessed source code to file. Default `[ '.ii', '.s' ]` The `.i` option is added
	      automaticall for '.c' files

    - `$GCCCPP_SUFFIXES`
	    - list of file suffixes that can be pre-processed by the compiler, so the pre-processed output
	      can be expected from the compiler, with the proper options. Default:
	      `[ '.c', '.cc', '.cpp', '.cxx', '.c++', '.C++', '.C' ]`

    - `$GCCCPP_INJECTED`
	    - set to `True` when the tool is imported in the environment. Can be later used to check if this
	      tool is already available in a given environment.

## Vim support function

If you have multiple sub-projects with their own tag files `tags` (and `lib.tags`) and cross-reference files
`cscope.out` (and `cscope.lib.out`), you can use the below function with the `Vim` editor to load them all
for source browsing while editing:

Load tag files function:
```vim
function g:LoadTagFiles(...)
    if a:0 > 1
	let l:depth_levels = a:1
	let l:path = a:2
	let l:tag_file = a:3
	let l:subdir_list = [ ]

	if !l:depth_levels
	    return
	endif

	let l:tagfile_found = v:false

	for l:entry in globpath(l:path, '*', v:true, v:true)
	    if isdirectory(l:entry)
		let l:entry_basename = fnamemodify(l:entry, ':t')

		if l:entry_basename != '.git'
		    let l:entry = substitute(substitute(l:entry, '\', '\\', '\V'), ',', '\,', '\V')
		    let l:subdir_list = add(l:subdir_list, l:entry)
		endif
	    else
		let l:basename = fnamemodify(l:entry, ':t')
		if l:basename == l:tag_file
		    " echomsg "Found tag file: " . l:basename . " in directory " . fnamemodify(l:entry, ':h')
		    let l:location = fnamemodify(l:entry, ':h')

		    execute 'set tags-=' . substitute(fnameescape(l:entry), '\v^\.\/', '', '')
		    execute 'set tags+=' . substitute(fnameescape(l:entry), '\v^\.\/', '', '')

		    let l:tagfile_found = v:true
		endif
	    endif
	endfor

	if len(l:subdir_list)
	    call LoadTagFiles(l:depth_levels - 1, join(l:subdir_list, ','), l:tag_file)
	endif
    else
	if a:0
	    let l:depth_levels = a:1
	else
	    let l:depth_levels = 4
	endif

	for tagname in [ 'lib.tags', 'tags' ]
	    for updir in [ './../../../../', './../../../', './../../', './../', './' ]
		execute 'set tags-=' . updir . tagname
		execute 'set tags^=' . updir . tagname
	    endfor
	endfor

	call LoadTagFiles(l:depth_levels, '.', 'tags')

	if exists('+tagrelative') && &tagrelative
	    if filereadable('../tags')
		set tags+=../tags
	    endif
	endif

	call LoadTagFiles(l:depth_levels, '.', 'lib.tags')

	if exists('+tagrelative') && &tagrelative
	    if filereadable('../lib.tags')
		set tags+=../lib.tags
	    endif
	endif

	for tagfile in split(&tags, ',')
	    echomsg('tag: ' . tagfile)
	endfor

	set tagrelative?
    endif
endfunction

command LoadTagFiles    call g:LoadTagFiles()
```

Load cross-reference files function:

```vim
function g:LoadCScopeFiles(...)
    if a:0 > 1
	let l:depth_levels = a:1
	let l:path = a:2
	let l:cscope_file = a:3
	let l:subdir_list = [ ]

	if !l:depth_levels
	    return
	endif

	for l:entry in globpath(l:path, '*', v:true, v:true)
	    if isdirectory(l:entry)
		let l:entry = substitute(substitute(l:entry, '\', '\\', '\V'), ',', '\,', '\V')
		let l:subdir_list = add(l:subdir_list, l:entry)
	    else
		let l:basename = fnamemodify(l:entry, ':t')
		if l:basename == l:cscope_file
		    echomsg "Found cscope file: " . l:basename . " in directory " . fnamemodify(l:entry, ':h')
		    let l:location = fnamemodify(l:entry, ':h')

		    if l:location == '.'
			execute 'cscope add ' . fnameescape(l:entry)
		    else
			execute 'cscope add ' . fnameescape(l:entry) . ' ' . fnameescape(fnamemodify(l:entry, ':h'))
		    endif
		endif
	    endif
	endfor

	if len(l:subdir_list)
	    call LoadCScopeFiles(l:depth_levels - 1, join(l:subdir_list, ','), l:cscope_file)
	endif
    else
	if a:0
	    let l:depth_levels = a:1
	else
	    let l:depth_levels = 4
	endif

	call LoadCScopeFiles(l:depth_levels, '.', 'cscope.out')
	call LoadCScopeFiles(l:depth_levels, '.', 'cscope.lib.out')

	if filereadable('../cscope.out')
	    cscope add ../cscope.out ../
	endif

	if filereadable('../cscope.lib.out')
	    cscope add ../cscope.lib.out ../
	endif

	redrawstatus
	cscope show
    endif
endfunction

command LoadCScopeFiles call g:LoadCScopeFiles()
```
Key mapping to load tag and xref files, and set the '[tagrelative](https://vimhelp.org/tagsrch.txt.html#tagrelative-option)'
option:

```vim
map <S-F5> :set tagrelative <Bar> execute 'LoadCScopeFiles' <Bar> execute 'LoadTagFiles'<CR>
```

Copy the functions above in your `~/.vimrc` file (create one if needed), change the last line
if you want a different key shortcut then `Shift + F5`, and use the shortcut in `Vim` when your
project is open, usually in the top project directory, to load all cross-reference and tag
files. If you re-generate the cross-reference using `scons`, while `Vim` is still using them,
remember to type `:cscope reset` to re-load them.

license: Unlicense

repository: terminatorul/xref-tag

repo_name: terminatorul/xref-tag


text:
# Gradient-Generator-Javascript

A Gradient Generator Web App built with HTML, CSS and JavaScript.

Give this a star, this motivates us to make cool stuff here.

- Built for making random Gradients.

## Check Out

Check out this project live on
https://stupid-kid-af.github.io/Gradient-Generator-Javascript/

Love random stuff, check out Random-Gradient-Generator
https://random-gradient-gen.netlify.app/

## Screenshots

![Screenshot from 2021-10-02 08-55-19](https://user-images.githubusercontent.com/54206927/135702172-aff621c4-08e6-4e40-95b7-600842ec652d.png)
![Screenshot from 2021-10-02 08-55-23](https://user-images.githubusercontent.com/54206927/135702173-1b5103d0-d0df-4437-89b6-28723e64f248.png)
![Screenshot from 2021-10-02 08-55-25](https://user-images.githubusercontent.com/54206927/135702174-10f68502-fbd2-4b07-8262-90ef400d2a87.png)
![Screenshot from 2021-10-02 08-55-29](https://user-images.githubusercontent.com/54206927/135702176-b1aaa149-c9c7-4899-8fea-43500b784040.png)
![Screenshot from 2021-10-02 08-55-33](https://user-images.githubusercontent.com/54206927/135702177-a7fcfbb2-2ea9-4e5c-abca-dfb89b668e7a.png)
![Screenshot from 2021-10-02 08-55-49](https://user-images.githubusercontent.com/54206927/135702178-1a14a424-860b-4f28-a31c-93496afc5734.png)
![Screenshot from 2021-10-02 08-55-56](https://user-images.githubusercontent.com/54206927/135702179-b850c896-eb20-4e95-9eb0-cc1c07d77609.png)
![Screenshot from 2021-10-02 08-56-00](https://user-images.githubusercontent.com/54206927/135702180-ca26188c-c711-4c32-a6c5-8fcfb9044de4.png)
![Screenshot from 2021-10-02 08-56-03](https://user-images.githubusercontent.com/54206927/135702181-d71ed351-dd52-45bc-9a1e-bc35cdf5bc7b.png)
![Screenshot](https://user-images.githubusercontent.com/54206927/135630750-2a80a287-b2c1-43dc-af6a-af0a66403b18.png)

## Contributing

Contributions are always welcome!

See `contributing.md` in "github/contributing.md" for ways to get started.

Please adhere to this project's `code of conduct`.

For reporting a bug go through `bug_report.md` in "github/bug_report.md".

## Run Locally

Clone the project

```bash
  git clone https://github.com/stupid-kid-af/Gradient-Generator-Javascript.git
```

Go to the project directory

```bash
  cd Gradient-Generator-Javascript
```

Start the server

```bash
  google-chrome index.html
            or
  <Browser> index.html
```

## Roadmap

- Additional shades support

- Add more integrations

- You tell me

## License

[MIT](https://choosealicense.com/licenses/mit/)

## Badges

[![MIT License](https://img.shields.io/apm/l/atomic-design-ui.svg?)](https://github.com/tterb/atomic-design-ui/blob/master/LICENSEs)

## Appendix

Feel free to ask questions related to development!

## Feedback

If you have any feedback, please reach out to us at<EMAIL_ADDRESS>                or
@stupid_kid_af  on Telegram.
## Support

For support, email<EMAIL_ADDRESS>or join our Telegram channel.

license: MIT

branch_name: refs/heads/master

extension: md

license_type: permissive


text:
# Node Webkit Agent
[![Stories in Ready](https://badge.waffle.io/c4milo/node-webkit-agent.png?label=ready)](https://waffle.io/c4milo/node-webkit-agent)

This module is an implementation of
[Chrome developer tools protocol](http://code.google.com/chrome/devtools/docs/protocol/1.0/index.html).
It is still pretty much a work in progress and only heap and CPU profilers are working right now. Help is wanted to finish implementing debugger, networking and console agents as well as a implementing from scratch a flamegraphs agent.

## Features
This module allows you to debug and profile remotely your nodejs applications
leveraging the following features by re-using the [built-in devtools front-end](http://code.google.com/chrome/devtools/docs/overview.html)
that comes with any webkit-based browsers such as Chrome or Safari.

## Installation
`npm install webkit-devtools-agent`

## Usage
From within your Node application, just require the module as usual, and start the agent. For example:

```javascript
var agent = require('webkit-devtools-agent');
agent.start()
```

Once the agent is initiated, use any of the following hosted Devtools UIs to profile your application.

**Node v0.6.x:** http://c4milo.github.io/node-webkit-agent/19.0.1084.46/inspector.html?host=localhost:9999&page=0

**Node v0.8.x and v0.10.x:** http://c4milo.github.io/node-webkit-agent/26.0.1410.65/inspector.html?host=localhost:9999&page=0

You can also use your browser's devtools frontend. It's important to make sure your browser supports websockets, otherwise the UI won't be able to connect to the node agent whatsoever.

You can also change the agent port and binding address where it listen to by setting up the following parameters:

* **port:** The port for the Devtools UI to connect to using websockets. Set to `9999` by default
* **bind_to:** The host or IP address where the websockets service is going to be bound to. Set to `<IP_ADDRESS>` by default
* **ipc_port:** IPC port for internal use. Set to `3333` by default
* **verbose:** Whether to log more information or not. Set to `false` by default

See the example below to understand better how to set these parameters.

### Example
A more elaborated example looks like:

```javascript

var agent = require('./index');

// Assume this HTTP service is your service
var http = require('http');
http.createServer(function (req, res) {
    console.log('boooo');
    res.writeHead(200, {'Content-Type': 'text/plain'});
    res.end('Hello World\n');
}).listen(9000, '<IP_ADDRESS>');
console.log('Server running at http://<IP_ADDRESS>:9000/ , pid-> ' + process.pid);

// Now let's have a signal handler for SIGUSR2 that is going
// to activate the devtools agent. You can use any other means to activate
// the agent, not just signal handlers.
process.on('SIGUSR2', function () {
  if (agent.server) {
    agent.stop();
  } else {
    agent.start({
        port: 9999,
        bind_to: '<IP_ADDRESS>',
        ipc_port: 3333,
        verbose: true
    });
  }
});

```

## ABI compatibility
[ABI](http://en.wikipedia.org/wiki/Application_binary_interface) compatibility breaks between Node v0.6.x and v0.8.x. Therefore, if you switch Node versions you would have to re-install `webkit-devtools-agent` again. See issue [#11](https://github.com/c4milo/node-webkit-agent/issues/11).

## Screenshots
### CPU profiling
![Screenshot](https://i.cloudup.com/YysNMMGE3a.png)

### Heap Profiling
![Screenshot](https://i.cloudup.com/WR5MKG6i02.png)

Happy Debugging!

## License
(The MIT License)

Copyright 2014 Camilo Aguilar. All rights reserved.

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.

 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.

repository: hariDasu/nodeIndexing

repo_name: hariDasu/nodeIndexing


text:
---
path: /events/2018-09-11-building-bots-with-the-web-speech-api/
title: Building Bots with the Web Speech API
type: event
start: 2018-09-11T18:30:00+01:00
end: 2018-09-11T20:00:00+01:00
presenter: Alex Lakatos
presenter_url: http://alexlakatos.com/
presenter_img: https://avatars3.githubusercontent.com/u/690132?v=4
presenter_bio: |

  Alex Lakatos is a JavaScript Developer Advocate for
  [Nexmo](https://www.nexmo.com/).

  In his spare time he volunteers at Mozilla as a Tech Speaker and a [Reps
  Mentor](https://reps.mozilla.org/u/alex_lakatos/).

  JavaScript developer building on the open web, he has been pushing its
  boundaries every day.  You can check out his github profile or get in touch on
  twitter.  When he's not programming in London, he likes to travel the world,
  so it's likely you'll bump into him in an airport lounge.

github_url: https://github.com/AlexLakatos
twitter_url: https://twitter.com/lakatos88
meetup_url: https://www.meetup.com/NottsJS/events/sfwwlpyxmbpb/
---

We're entering a promising new era of computing.

The advance of machine learning and artificial intelligence is reviving interest
in conversational interfaces.  This creates the potential for conversation as
the new mode of interaction with technology.

The big problem is recognizing spoken input has been mostly solved, but a new
challenge has arisen: how to build a user experience that's modelled after
natural human conversation.

This talk outlines the basic mechanics of conversation, introduces core
principles to design by, and presents you with a practical UI to start creating
conversational experiences that engage, delight, and truly help your users.
We'll also be building a voice enabled bot using JavaScript!

repository: nottsjs/website

gha_language: JavaScript

gha_license_id: MIT

repo_name: nottsjs/website


text:
###Python cffi bridge to fontconfig's FcFontList/FcFontMatch

Useful for python programs that need to query information about fonts installed
in the system(use this instead of parsing fc-list output). Requires the
fontconfig shared library installed in a directory that the cffi module can
find.

###Usage

```python
from fclist import fclist, fcmatch

# Print the family, style and file path of monospace/truetype fonts
for font in fclist(spacing='mono', fontformat='TrueType'):
    print font.family, font.style, font.file

# Print the system's default monospace font
print fcmatch('monospace')
```

`fclist` can receive any keyword arguments that can be passed to the `fc-list`
command, and the returned font objects have most attributes defined by
fontconfig.h.

`fcmatch` receives the same pattern that is normally passed to `fc-match`, but
it doesn't support the --all/--sort options(only returns a single font object).

repository: tarruda/python-fclist

gha_language: Python

repo_name: tarruda/python-fclist


text:
# GACO

GACO is a web plataform to assist the management of eletronic waste in São Paulo and was made with [Laravel](http://laravel.com/docs).

## Install

`$ sudo apt-get install php-common php-mbstring php-xml php-curl`

## Run

`$ php artisan serve`

## License

Gaco is under [MIT License](LICENSE).

repository: filipefilardi/GACO

gha_language: PHP

repo_name: filipefilardi/GACO


text:
# ms.macro

[![Dependency Status](https://img.shields.io/david/knpwrs/ms.macro.svg)](https://david-dm.org/knpwrs/ms.macro)
[![devDependency Status](https://img.shields.io/david/dev/knpwrs/ms.macro.svg)](https://david-dm.org/knpwrs/ms.macro#info=devDependencies)
[![Greenkeeper badge](https://badges.greenkeeper.io/knpwrs/ms.macro.svg)](https://greenkeeper.io/)
[![Build Status](https://img.shields.io/travis/knpwrs/ms.macro.svg)](https://travis-ci.org/knpwrs/ms.macro)
[![Npm Version](https://img.shields.io/npm/v/ms.macro.svg)](https://www.npmjs.com/package/ms.macro)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Badges](https://img.shields.io/badge/badges-7-orange.svg)](http://shields.io/)

Convert various time formats to milliseconds at build time in Babel.

## Usage

Simply install and configure [`babel-macros`] and then use `ms.macro` the same
way you use [`ms`].

## Example

Given the following input:

```js
import ms from 'ms.macro';

const ONE_DAY = ms('1 day');
const TWO_DAYS = ms('2 days');
```

Babel will produce the following output:

```js
const ONE_DAY = 86400000;
const TWO_DAYS = 172800000;
```

It also works as a tagged template literal:

```js
const ONE_DAY = ms`1 day`;
const TWO_DAYS = ms`2 days`;
```

That will produce the same output as the function version.

## FAQ

### What are the advantages of running `ms` as a macro?

The two main advantages of running `ms` as a macro are that there are no
runtime dependencies and any errors (such as mistakenly calling`ms('1 da')`
instead of `ms('1 day')`) become build-time errors rather than run-time errors.

### Are there any disadvantages of running `ms` as a macro?

This macro only supports the single string-argument signature of [`ms`], i.e.,
passing a single string and getting back a number. This is because when you are
converting a number of milliseconds to an equivalent string representation you
are typically using calculated values not available at build-time. If you want
to convert a number of milliseconds to an equivalent string representation you
should use the [`ms`] package directly. If you want to use both packages
together, you can give the imported values different names:

```js
import ms from 'ms';
import msm from './ms.macro';

const ONE_DAY = msm('1 day');
const str = ms(172800000);
```

That will result in the following output:

```js
import ms from 'ms';

const ONE_DAY = 86400000;
const str = ms(172800000);
```

## License

**MIT**

[`babel-macros`]: https://github.com/kentcdodds/babel-macros "babel-macros"
[`ms`]: https://github.com/zeit/ms "ms"


text:
# Lesson: Classes

Every type is either a reference or a primitive. Classes, enums, and arrays (which all inherit from
[`java.lang.Object`](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html)) as well as interfaces are all reference types. Examples of reference types include
[`java.lang.String`](https://docs.oracle.com/javase/8/docs/api/java/lang/String.html), all of the wrapper classes for primitive types such as
[`java.lang.Double`](https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html), the interface
[`java.io.Serializable`](https://docs.oracle.com/javase/8/docs/api/java/io/Serializable.html), and the enum
[`javax.swing.SortOrder`](https://docs.oracle.com/javase/8/docs/api/javax/swing/SortOrder.html). There is a fixed set of primitive types: `boolean`, `byte`, `short`, `int`, `long`, `char`, `float`, and `double`.

For every type of object, the Java virtual machine instantiates an immutable instance of
[`java.lang.Class`](https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html) which provides methods to examine the runtime properties of the object including its members and type information.
[`Class`](https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html) also provides the ability to create new classes and objects. Most importantly, it is the entry point for all of the Reflection APIs. This lesson covers the most commonly used reflection operations involving classes:

[Retrieving Class Objects](classNew.html) describes the ways to get a
[`Class`](https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html)

- [Examining Class Modifiers and Types](classModifiers.html) shows how to access the class declaration information
- [Discovering Class Members](classMembers.html) illustrates how to list the constructors, fields, methods, and nested classes in a class

[Troubleshooting](classTrouble.html) describes common errors encountered when using
[`Class`](https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html)

path: /_drafts/BigJava/The Reflection API/The Reflection API.md

filename: The Reflection API.md


text:
# Configuration

The linter contains a list of core rules, and by default, they are all enabled.
However, one can disable a rule by using a CLI flag, a configuration file or the file
comments.

## CLI flag

We can disable a rule using the `-disable_rule` flag.

Example:

Disable the rule `core::0140::lower-snake`:

```sh
api-linter -disable_rule core::0140::lower-snake test.proto
```

To disable multiple rules, specify the flag multiple times respectively:

```sh
api-linter -disable_rule core::0140::lower-snake -disable_rule core::0131::request-name-field test.proto
```

## Configuration file

The linter accepts a configuration file using the `-config` CLI switch.

Examples:

Disable the rule `core::0140::lower-snake` for any proto files under the
directory `tests` using a JSON config file:

```json
[
  {
    "included_paths": ["tests/**/*.proto"],
    "disabled_rules": ["core::0140::lower-snake"]
  }
]
```

Disable the same rule using a YAML config file:

```yaml
---
- included_paths:
    - 'tests/**/*.proto'
  disabled_rules:
    - 'core::0140::lower-snake'
```

## Proto comments

Examples:

Disable the rule `core::0140::lower-snake` for the entire file:

```proto
// A file comment:
// (-- api-linter: core::0140::lower-snake=disabled --)
//
// The above comment will disable the rule
// `core::0140::lower-snake` for the entire file.

syntax = "proto3";

package google.api.linter.examples;

message Example {
    string badFieldName = 1;
    string anotherBadFieldName = 2;
}
```

Disable the same rule only for a field by using a leading comment:

```protobuf
syntax = "proto3";

package google.api.linter.examples;

message Example {
    // This field will trigger a lint error.
    string badFieldName = 1;

    // This field will not trigger a lint error.
    // (-- api-linter: core::0140::lower-snake=disabled --)
    string anotherBadFieldName = 2;
}
```

repository: RocketDonkey/api-linter

branch_name: refs/heads/main

repo_name: RocketDonkey/api-linter


text:
# T1136.001 - Create Account: Local Account
## [Description from ATT&CK](https://attack.mitre.org/techniques/T1136/001)

Adversaries may create a local account to maintain access to victim systems. Local accounts are those configured by an organization for use by users, remote support, services, or for administration on a single system or service. With a sufficient level of access, the net user /add command can be used to create a local account. On macOS systems the dscl -create command can be used to create a local account. Local accounts may also be added to network devices, often via common [Network Device CLI](https://attack.mitre.org/techniques/T1059/008) commands such as username.(Citation: cisco_username_cmd)

Such accounts may be used to establish secondary credentialed access that do not require persistent remote access tools to be deployed on the system.

## Atomic Tests

- [Atomic Test #1 - Create a user account on a Linux system](#atomic-test-1---create-a-user-account-on-a-linux-system)

- [Atomic Test #2 - Create a user account on a MacOS system](#atomic-test-2---create-a-user-account-on-a-macos-system)

- [Atomic Test #3 - Create a new user in a command prompt](#atomic-test-3---create-a-new-user-in-a-command-prompt)

- [Atomic Test #4 - Create a new user in PowerShell](#atomic-test-4---create-a-new-user-in-powershell)

- [Atomic Test #5 - Create a new user in Linux with `root` UID and GID.](#atomic-test-5---create-a-new-user-in-linux-with-root-uid-and-gid)

- [Atomic Test #6 - Create a new Windows admin user](#atomic-test-6---create-a-new-windows-admin-user)

## Atomic Test #1 - Create a user account on a Linux system
Create a user via useradd

**Supported Platforms:** Linux

**auto_generated_guid:** 40d8eabd-e394-46f6-8785-b9bfa1d011d2

#### Inputs:
| Name | Description | Type | Default Value |
|------|-------------|------|---------------|
| username | Username of the user to create | string | evil_user|

#### Attack Commands: Run with `bash`!  Elevation Required (e.g. root or admin)

```bash
useradd -M -N -r -s /bin/bash -c evil_account #{username}
```

#### Cleanup Commands:
```bash
userdel #{username}
```

## Atomic Test #2 - Create a user account on a MacOS system
Creates a user on a MacOS system with dscl

**Supported Platforms:** macOS

**auto_generated_guid:** 01993ba5-1da3-4e15-a719-b690d4f0f0b2

#### Inputs:
| Name | Description | Type | Default Value |
|------|-------------|------|---------------|
| username | Username of the user to create | string | evil_user|
| realname | 'realname' to record when creating the user | string | Evil Account|

#### Attack Commands: Run with `bash`!  Elevation Required (e.g. root or admin)

```bash
dscl . -create /Users/#{username}
dscl . -create /Users/#{username} UserShell /bin/zsh
dscl . -create /Users/#{username} RealName "#{realname}"
dscl . -create /Users/#{username} UniqueID "1010"
dscl . -create /Users/#{username} PrimaryGroupID 80
dscl . -create /Users/#{username} NFSHomeDirectory /Users/#{username}
```

#### Cleanup Commands:
```bash
dscl . -delete /Users/#{username}
```

## Atomic Test #3 - Create a new user in a command prompt
Creates a new user in a command prompt. Upon execution, "The command completed successfully." will be displayed. To verify the
new account, run "net user" in powershell or CMD and observe that there is a new user named "T1136.001_CMD"

**Supported Platforms:** Windows

**auto_generated_guid:** 6657864e-0323-4206-9344-ac9cd7265a4f

#### Inputs:
| Name | Description | Type | Default Value |
|------|-------------|------|---------------|
| username | Username of the user to create | string | T1136.001_CMD|
| password | Password of the user to create | string | T1136.001_CMD!|

#### Attack Commands: Run with `command_prompt`!  Elevation Required (e.g. root or admin)

```cmd
net user /add "#{username}" "#{password}"
```

#### Cleanup Commands:
```cmd
net user /del "#{username}" >nul 2>&1
```

## Atomic Test #4 - Create a new user in PowerShell
Creates a new user in PowerShell. Upon execution, details about the new account will be displayed in the powershell session. To verify the
new account, run "net user" in powershell or CMD and observe that there is a new user named "T1136.001_PowerShell"

**Supported Platforms:** Windows

**auto_generated_guid:** bc8be0ac-475c-4fbf-9b1d-9fffd77afbde

#### Inputs:
| Name | Description | Type | Default Value |
|------|-------------|------|---------------|
| username | Username of the user to create | string | T1136.001_PowerShell|

#### Attack Commands: Run with `powershell`!  Elevation Required (e.g. root or admin)

```powershell
New-LocalUser -Name "#{username}" -NoPassword
```

#### Cleanup Commands:
```powershell
Remove-LocalUser -Name "#{username}" -ErrorAction Ignore
```

## Atomic Test #5 - Create a new user in Linux with `root` UID and GID.
Creates a new user in Linux and adds the user to the `root` group. This technique was used by adversaries during the Butter attack campaign.

**Supported Platforms:** Linux

**auto_generated_guid:** a1040a30-d28b-4eda-bd99-bb2861a4616c

#### Inputs:
| Name | Description | Type | Default Value |
|------|-------------|------|---------------|
| username | Username of the user to create | string | butter|
| password | Password of the user to create | string | BetterWithButter|

#### Attack Commands: Run with `bash`!  Elevation Required (e.g. root or admin)

```bash
useradd -g 0 -M -d /root -s /bin/bash #{username}
if [ $(cat /etc/os-release | grep -i 'Name="ubuntu"') ]; then echo "#{username}:#{password}" | sudo chpasswd; else echo "#{password}" | passwd --stdin #{username}; fi;
```

#### Cleanup Commands:
```bash
userdel #{username}
```

## Atomic Test #6 - Create a new Windows admin user
Creates a new admin user in a command prompt.

**Supported Platforms:** Windows

**auto_generated_guid:** fda74566-a604-4581-a4cc-fbbe21d66559

#### Inputs:
| Name | Description | Type | Default Value |
|------|-------------|------|---------------|
| username | Username of the user to create | string | T1136.001_Admin|
| password | Password of the user to create | string | T1136_pass|

#### Attack Commands: Run with `command_prompt`!  Elevation Required (e.g. root or admin)

```cmd
net user /add "#{username}" "#{password}"
net localgroup administrators "#{username}" /add
```

#### Cleanup Commands:
```cmd
net user /del "#{username}" >nul 2>&1
```

repository: redcanaryco/atomic-red-team

gha_language: C

repo_name: redcanaryco/atomic-red-team


text:
---
layout: page
title: Michael's Project Portfolio Page
---

## Project: RemindMe

RemindMe is a desktop application for keeping track of user events and deadlines, optimised for use via Command Line
Interface(CLI) while still having the benefits of a Graphic User Interface(GUI).
RemindMe allows students to always be aware of exams and events deadline as there will be reminder pop-ups and calendar
for students to see!

## Summary of Contributions

Given below are my contributions to the project.

* **New Feature**: Delete modules, assignments, exams and general events.
    * What it does: allows the user to manage their tasks in terms of modules, assignments, exams and general events
       by deleting tasks and events that are no longer needed or relevant.
    * Justification: This feature improves RemindMe significantly as it allows the user to delete entries
      so that the task window does not become too cluttered
    * Highlights: This enhancement affects all the other functionality of RemindMe.
    * Credits: *{AddressBook3's Person and AddressBook3's AddressBook}*

* **New Feature**: Added the ability to add modules, assignments, exams and general events.
    * What it does: allows the user to add modules, assignments, exams and general events in RemindMe.
    * Justification: This feature improves RemindMe significantly as it allows the user to add entries of different natures to RemindMe
      with proper categorisation. This provides a convenient way to view the different types of tasks that the user has.
    * Highlights: This enhancement affects the existing add command, which could only add persons. It required the need to add in a parser for add commands
      to differentiate between adding persons, modules, assignments, exams and general events. Therefore, this implementation required adding of new classes and a change in the logic of RemindMe.
    * Credits: *{AddressBook3's Parser and AddressBook3's AddPersonCommand}*

* **Code contributed**: [RepoSense link](https://nus-cs2103-ay2021s2.github.io/tp-dashboard/?search=w15&sort=groupTitle&sortWithin=title&timeframe=commit&mergegroup=&groupSelect=groupByRepos&breakdown=true&checkedFileTypes=docs~functional-code~test-code~other&since=2021-02-19&tabOpen=true&tabType=authorship&tabAuthor=maikongeh&tabRepo=AY2021S2-CS2103T-W15-1%2Ftp%5Bmaster%5D&authorshipIsMergeGroup=false&authorshipFileTypes=docs~functional-code~test-code~other&authorshipIsBinaryFileTypeChecked=false)

* **Project management**:
  * Managed releases `v1.2` - `v1.4`

* **Enhancements to existing features**:
    * Wrote additional tests for new features (Pull requests
    [\#122](https://github.com/AY2021S2-CS2103T-W15-1/tp/pull/122),
    [\#248](https://github.com/AY2021S2-CS2103T-W15-1/tp/pull/248),
    [\#324](https://github.com/AY2021S2-CS2103T-W15-1/tp/pull/324),
    [\#352](https://github.com/AY2021S2-CS2103T-W15-1/tp/pull/352))

    * Added done command for assignment. This allows the toggle the done status of an Assignment.
    (Pull requests [\#183](https://github.com/AY2021S2-CS2103T-W15-1/tp/pull/183))

* **Documentation**:
    * User Guide:
        * Added documentations for the features `done` and `delete`
        (Pull request [\#193](https://github.com/AY2021S2-CS2103T-W15-1/tp/pull/193))

        * Added documentation for UG.
        (Pull requests  [\#46](https://github.com/AY2021S2-CS2103T-W15-1/tp/pull/46),
                        [\#174](https://github.com/AY2021S2-CS2103T-W15-1/tp/pull/174))

    * Developer Guide:
        * Add implementation details of the `delete` feature.

gha_language: Java

gha_license_id: NOASSERTION


text:
## Kubernetes Version Support

`Nocalhost` supports Major:"1", Minor:"12+" versions of kubernetes, but we recommend that you to use v1.16+.

That's because if your want to use [service dependencies](../../best-practice/service-best/#service_2) control between services:

- Ensure that the Kubernetes cluster is at least as new as v1.16 (to use `admissionregistration.k8s.io/v1`), or v1.9 (to use `admissionregistration.k8s.io/v1beta1`).
- Ensure that MutatingAdmissionWebhook and ValidatingAdmissionWebhook admission controllers are enabled. [Here](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#is-there-a-recommended-set-of-admission-controllers-to-use) is a recommended set of admission controllers to enable in general.
- Ensure that the `admissionregistration.k8s.io/v1` or `admissionregistration.k8s.io/v1beta1` API is enabled.

see [adminssion web hooks](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#prerequisites).

## Increase Inotify Limit

If your file synchronization is too slow in linux, it is most likely due to inotify limit.

### How do I increase the inotify limit to get my filesystem watcher to work?

Linux typically restricts the amount of watches per user (usually 8192). When you have more directories you need to adjust that number.

On many Linux distributions you can run the following to fix it:

```shell
echo "fs.inotify.max_user_watches=204800" | sudo tee -a /etc/sysctl.conf
```

On Arch Linux and potentially others it is preferred to write this line into a separate file, i.e. you should run:
```shell
echo "fs.inotify.max_user_watches=204800" | sudo tee -a /etc/sysctl.d/90-override.conf
```

This only takes effect after a reboot. To adjust the limit immediately, run:

```shell
sudo sh -c 'echo 204800 > /proc/sys/fs/inotify/max_user_watches'
```

## Why Nocalhost can not clone codes with SSH key that need passphrase for SSH private keys?

Nocalhost does not support currently. We will support it later.

 So you need to adjust the permissions for the data directory mapped:

```
chown -R 1001:1001 /foo/bar
```

gha_language: HTML


text:
Chapter VII : Application Testing
================================

A full Tests report can be found [here](https://rent-vehicle-test-report.netlify.app/index.html "tests report").

## Unit Test

Unit testing an applications has many benefits such as ensuring every component of the latter works as expected,
facilitates code refactoring & design improvement and more importantly reduces bug fixing cost.

**JUnit** was used as a unit testing tool in this application.

```{.java caption="Assert username can be found"}

 @Test
 @DisplayName("assert that user can be found by username")
 public void assertThatUserCanBeFoundByUsername() {
   var userDetails = domainUserDetailsService.loadUserByUsername(USER_ONE_LOGIN);
   assertThat(userDetails).isNotNull();
   assertThat(userDetails.getUsername()).isEqualTo(USER_ONE_LOGIN);
}

```

## Integration Test

```{.java caption="Should get one car by its id"}

 @Test
 @Transactional
 @DisplayName("should get one car by its id")
 public void getCar() throws Exception {

   // Initialize the database
   var savedCar = carDAO.saveAndFlush(car);

   restCarMockMvc
    .perform(get("/api/v1/cars/{id}", savedCar.getId()))
    .andExpect(status().isOk())
    .andExpect(jsonPath("$.isDamaged").value(DEFAULT_IS_DAMAGED))
    .andExpect(jsonPath("$.licensePlate").value(DEFAULT_LICENSE_PLATE))
}

```

\pagebreak

Integration testing plays a major role in the application development cycle by making sure the backend endpoints
work as expected. To achieve the latter, **MockMvc**[^8] was used to test the web layer and perform requests against
a mocked servlet environment. There were no real HTTP request going around during the integration tests since
the latter are executed in a mocked environment provided by Spring.

## Architecture Testing - ArchUnit[^9]

\begin{tcolorbox}[colback=green!5,colframe=green!35!black,
title=What is ArchUnit ?,coltitle=white, fonttitle=\bfseries]

\textbf{ArchUnit} is a free, simple and extensible library for checking the architecture of your Java code. That is,
ArchUnit can check dependencies between packages and classes, layers and slices, check for cyclic dependencies and
more. It does so by analyzing given Java bytecode, importing all classes into a Java code structure. ArchUnit’s
main focus is to automatically test architecture and coding rules, using any plain Java unit testing framework.

\rightline{{\rm --- From archunit.org}}

\end{tcolorbox}

### ArchUnit To The Rescue

A common problem that occurs quite often in a Software Development Life Cycle is that code implementation can often
diverge from the initial design and architecture. This is where ArchUnit comes into play to test that a code
implementation is consistent with the initially defined design.

One of the main reason of software architecture, when it comes to codebase, is maintainability, and to keep an
application maintainable, testable, and extendable, an effort to make sure it is modular, interdependencies
are as small as possible and there no loose coupling between components needs to be made.

Furthermore, in an evolving application, implementation rules evolve over time. The use of ArchUnit tests
forces us developers to purposely accept deviations from predefined rules instead of haphazardly encountering
them later in a test feature or actually never. ArchUnit issues warnings about deviations.

ArchUnit allowed me to test the following :

- Package dependency
- Class dependency
- Naming conventions
- Layered packages constraints

```{.java caption="Layer Dependencies"}

 @Test
 @DisplayName("layer dependencies should be respected")
 public void layer_dependencies_are_respected() {

   layeredArchitecture()
     .layer("Controllers").definedBy("be.rentvehicle.web..")
     .layer("Services").definedBy("be.rentvehicle.service..")
     .layer("Persistence").definedBy("be.rentvehicle.dao..")

     .whereLayer("Controllers").mayNotBeAccessedByAnyLayer()
     .whereLayer("Services").mayOnlyBeAccessedByLayers("Controllers")
     .whereLayer("Persistence").mayOnlyBeAccessedByLayers("Services")
     .ignoreDependency(DomainUserDetailsService.class, UserDAO.class)
     .check(importedClasses);
}
```

## End-to-End Test - Puppeteer[^10]

E2E tests live demo [here](https://github.com/danny00747/vms/wiki/Test-Reports "e2e report").

An end-to-end tests are all about testing an application from the end customer’s perspective and making sure business
requirements are met. To achieve this feat, a Node library called Puppeteer was used.

### Puppeteer

**Puppeteer** is a browser automation Node library from the Google Chrome team which enables developers to control
Chrome/Chromium and execute common actions, much like in a real browser - programmatically, through a decent API.
Simply put, it’s a super useful and easy tool for automating, testing and scraping web pages. It runs headlessly by
default, but can be configured to run in headful mode which helps while debugging.

It's important to note that puppeteer \underline{is not} a testing tool. It doesn't come with built-in testing assertions,
it's just a tool for controlling the browser. But if it's used along with real testing tools such as Mocha & Chai,
we get a fascinating framework that can test the application as if it was being used by a customer.
In other words the combination of Mocha & Chai and Puppeteer helps test an application from the costumer's
perspective. \newline \newline

```{.js caption="E2E Test Example"}

describe('/POST Login', async () => {

   it('it should login a user', async () => {

       const pseudo = await page.$('#pseudo'); //
       const password = await page.$('#password');
       const submit = await page.$('#submitBtn');

       await pseudo.click({ clickCount: 3 });
       await pseudo.type('john@gmail.com');

       await password.click({ clickCount: 3});
       await password.type('az#azx=3*ùâzH2é01');

       await submit.click();
       await page.waitForNavigation();

       expect(page.url()).eql('http://localhost:4200/gallery');

       const logoutBtn = await page.$('#logoutBtn');
       await logoutBtn.click();
       await page.waitForNavigation();

       expect(page.url()).eql('http://localhost:4200/login');

   });
});

```

[^8]: [MockMvc](https://spring.io/guides/gs/testing-web)
[^9]: [ArchUnit](https://www.archunit.org)
[^10]: [Puppeteer](https://pptr.dev)

\pagebreak

path: /docs/tfe report/src/10_test.md


text:
## Introduction

The SpatioTemproal Asset Catalog is a specification to help interoperability, but the key to achieve that goal is a community
of like-minded collaborators who are building software and exposing data in a standard way. The specification is really
the result of that collaboration, and the aim is to provide a flexible base that others can extend and innovate on top of.
If others in the community create similar functionality with their geospatial access API's then the community will hopefully
evolve extension standards that enable increased interoperability.

Right now we are in the very early days of the collaboration. So while there is a core specification there is still quite a
few best practices to evolve and [improvements](roadmap.md) to the spec that will be needed.

## Implementations and Feedback

The best way to help out with STAC is to try to implement the specification, either a [static catalog](static-catalog/), a
[catalog api](api-spec) or even both. This can be done by extending existing catalog software, creating new software, or
standing up a service end point that exposes data. Implementations using the specification as it stands will likely
have to make a number of decisions while building, as there is a lot that is left unspecified. The best thing to do
is to document those decisions, and share them with the core STAC group. Ideally make mini-specifications, but even just
a write up with some sample output is great.

If you want to help out with STAC but don't have an obvious project - a piece of software, or data you want to expose - then
read on for ideas.

## Implementation Roadmap

This section lays out a path of implementations that will be necessary to make this a truly great specification. It describes
the hoped for ecosystem of tools and data that hopefully will come to pass. Many are things anyone could help out with an
implement. Some depend on particular knowledge or background, like deep involvement with an open source project. And some
only a few people are able to do, since they depend on working for a particular company.

In time we may try to track these in their own project, but for now this list should be sufficient. It is a complement
to the [roadmap](roadmap.md), which is just for the specification itself. But that roadmap will only evolve with this
set of work on real implementations to inform it.

### Tier 1

These tools are seen as the bare minimum to move STAC spec to a broader release, so that it has a base line of feedback from
real world implementations, and basic tooling to help data providers get their data out as STAC

**Static Catalog Creation Tooling** - At the core this should enable a user to take a directory of GeoTIFF's and create
a fully linked static catalog. It should autogenerate the time and geography fields, and prompt the user for additional information.
Ideally it would evolve to start to understand common metadata formats, to populate from existing metadata (and provide links
to the extended metadata). Command line tooling would be ideal, but could easily start requiring language specific scripting.

**STAC Validator** - A STAC validator tool would be able to take a root document of a static catalog or catalog API and crawl
all the links, checking for specification compliance. The core validation can leverage the JSON Schemas defined in the spec,
adding crawling on top of that. Ideally this could be stood up as a web service, to point at online STAC instances and check
compliance, but a command line / scripting language tool is fine to start. Would be cool if it also reported stats on the
catalogs validated - number of records, number of asset files, total asset data size referenced, etc.

**Online SpatioTemporal Asset Catalogs** - Ideally there are at least 5 different catalog instances, and at least 2 each of static
catalogs and catalog API's. These should be public services that people can hit to try out (though don't need to aim for
high reliability - it's ok if they go down sometimes). Can be open source or proprietary software (or obviously just
generated static files) - just the service should be public. Don't need to be the entire archives, but ideally at least
thousands of records.

**Open Source API Implementation** - There should be some open source code that shows how a STAC API can work, that anyone
can install and try out. Could be written in any language, and ideally there are implementations in many common languages.

**STAC Client Library** - A good first STAC client library would first enable searching and download of data from a STAC API.
Next steps could include crawling a static STAC and enabling querying of the crawled data (perhaps store in a geopackage), as
well as a nice command line tool.

### Tier 2

**API -> Static catalog tool** - Building on top of core client and server tooling in tier one can introduce some cool value add tools.
A client library that crawls a STAC API and can create a static STAC can be used as a 'backup' tool for an API, making a copy
of the catalog that can't go down (ideally this would extend the spec to have a link 'rel' type that refers back to the source
data as a [spec extension](https://github.com/radiantearth/stac-spec/blob/dev/roadmap.md#provenance--duplication-tracking).

**Static catalog -> API tool** - The flip of the previous tool,  a STAC API could crawl a static catalog and serve as a
dynamic query service on top of the core.

**Javascript Search Tools** - A javascript library that can search a STAC API and enable online querying of results. Hopefully
a core library, and then a full online implementation integrated with OpenLayers/Leaflet. Cool extensions would be integration
with a tiled server to display COG's (or javascript reading COG's directly), and the ability to read static catalogs
(potentially storing data in local storage).

**HTML STAC Implementations** - Though little work has been done yet the HTML versions of STAC are super important so the catalogs
are useful to people, not just machines. Ideally the static catalogs all have accompanying html files with interactive maps that
lets you zoom in to cloud-optimized geotiff's (or potentially even with html files generated on the file with javascript). And
there are also STAC API's that have html as an output in addition to json. Aiming for at least 5 html implementations.

**GDAL Implementation** - As the most used geospatial library it is important that GDAL be a tool that can query STAC catalogs,
both dynamic and static ones. Ideally GDAL could also create static catalogs as an output format.

**STAC Profile Implementations** - It is important that implementations start to create extensions to the core STAC fields,
for things like earth observation metadata fields, derived data, mosaics, point clouds, DEM/DSM, etc.

## Tier 3

**Major Public Data as static catalogs** - Ideally Landsat, Sentinel (1 & 2), NAIP, OpenAerialMap and at least a couple other public data
sources (CBERS? NASA data?)

**Vendors with STAC implementations** - Hopefully the data and software vendors also expose their major holdings & user's
data as STAC. Planet, DigitalGlobe, Airbus, Urthecast for providers, and ENVI, Erdas, Esri, etc for data. This may be a
mix of static catalogs (hopefully at least for open data) and catalog API's.

**Major Open Source Implementations** - Should aim for the leading open source libraries (GDAL, GeoTools) and tools (QGIS, GeoServer,
MapServer, OpenLayers, GeoNetwork, pycsw, GeoTrellis/RasterFoundry) to develop at least plugins to talk to and/or implement STAC

### Tier 4

**Additional Implementations** - More STAC API's, static API generation code and client libraries, in a variety of languages
and integrations, are always desired.

**Extensive metadata translation tools** - Static catalog generators ideally understand most any metadata format, to create
catalogs from all the existing metadata in the world.

**Syncing STACs** - An implementation where on catalog could subscribe to 'changes' of another catalog to stay in sync. Could
be two STAC API's, or could be a static catalog with an updating stream of file changes that a STAC API reads. The 'child'
catalog could be syncing with just a portion of the main one, like for their area of interest.

**Global STAC stats tools** - A tool that can crawl all publicly exposed STACs and present numbers on the total number of
records indexed in the network.

**STAC Libraries in all major languages** - There should be client libraries and server bindings for all major programming
languages.

**Cool Extensions** - STAC should be a core that others build cool advanced catalog functionality on. Things like aggregation,
both spatial (coverage maps) and fields (total stats, histograms), offline catalogs, crossfilter querying, faceted search,
etc.

repository: hobu/stac-spec

repo_name: hobu/stac-spec


text:
# FreeRTOS STM32F407 Eclipse Template
Template Project for STM32F4 project with FreeRTOS

Tested with :
Mars.1 Release (4.5.1)
    - CDT 8.8.0
    - gcc-arm-none-eabi-5_2-2015q4

To setup IDE & Debugging, follow theses tutorials from the great website :
http://gnuarmeclipse.github.io/install/


text:
# resume.html
an html based resume based off a json file

renders a resume based on a template ```resume.js``` file given,
which defines the json object that is your resume.
This json object is of a custom format and an example can be found
in the [krithik-resume branch](https://github.com/KritR/resume.html/blob/krithik-resume/resume.js).

[my resume demo](https://rawcdn.githack.com/KritR/resume.html/dd8b7a43920dced4e0f61aba01564aeac37f95b5/resume.html)