README.md

   1 [![Cirrus Build Status](https://api.cirrus-ci.com/github/elfmz/far2l.svg)](https://cirrus-ci.com/github/elfmz/far2l) [![Coverage Status](https://codecov.io/gh/elfmz/far2l/coverage.svg?branch=master)](https://codecov.io/gh/elfmz/far2l?branch=master) [![Coverity Scan](https://scan.coverity.com/projects/27038/badge.svg)](https://scan.coverity.com/projects/elfmz-far2l) [![Language Grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/elfmz/far2l.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/elfmz/far2l/context:cpp) [![Packages](https://repology.org/badge/tiny-repos/far2l.svg)](https://repology.org/project/far2l)
   2
   3 # far2l [![tag](https://img.shields.io/github/tag/elfmz/far2l.svg)](https://github.com/elfmz/far2l/tags)
   4 Linux fork of FAR Manager v2 (http://farmanager.com/)
   5 Works also on OSX/MacOS and BSD (but latter not tested on regular manner)
   6 BETA VERSION.
   7 **Use on your own risk!**
   8
   9 Plug-ins that are currently working: NetRocks (SFTP/SCP/FTP/FTPS/SMB/NFS/WebDAV), colorer, multiarc, tmppanel, align, autowrap, drawline, editcase, SimpleIndent, Calculator, Python (optional scripting support)
  10
  11 FreeBSD/MacOS (Cirrus CI): [![Cirrus](https://api.cirrus-ci.com/github/elfmz/far2l.svg)](https://cirrus-ci.com/github/elfmz/far2l)
  12
  13
  14 #### License: GNU/GPLv2
  15
  16 ### Used code from projects
  17
  18 * FAR for Windows and some of its plugins
  19 * WINE
  20 * ANSICON
  21 * Portable UnRAR
  22 * 7z ANSI-C Decoder
  23 * utf-cpp by ww898
  24
  25 ## Contributing, Hacking
  26 #### Required dependencies
  27
  28 * libwxgtk3.0-gtk3-dev (or libwxgtk3.2-dev in newer distributions, or libwxgtk3.0-dev in older ones, optional - needed for GUI backend, not needed with -DUSEWX=no)
  29 * libx11-dev (optional - needed for X11 extension that provides better UX for TTY backend wherever X11 is available)
  30 * libxi-dev (optional - needed for X11/Xi extension that provides best UX for TTY backend wherever X11 Xi extension is available)
  31 * libxerces-c-dev (optional - needed for Colorer plugin, not needed with -DCOLORER=no)
  32 * libuchardet-dev (optional - needed for auto charset detection, not needed with -DUSEUCD=no)
  33 * libssh-dev (optional - needed for NetRocks/SFTP)
  34 * libssl-dev (optional - needed for NetRocks/FTPS)
  35 * libsmbclient-dev (optional - needed for NetRocks/SMB)
  36 * libnfs-dev (optional - needed for NetRocks/NFS)
  37 * libneon27-dev (or later, optional - needed for NetRocks/WebDAV)
  38 * libarchive-dev (optional - needed for better archives support in multiarc)
  39 * libunrar-dev (optional - needed for RAR archives support in multiarc, see UNRAR command line option)
  40 * libpcre3-dev (or libpcre2-dev in older distributions, optional - needed for advanced custom archive formats support in multiarc)
  41 * cmake ( >= 3.2.2 )
  42 * pkg-config
  43 * g++
  44 * git (needed for downloading source code)
  45
  46 #### Or simply on Debian/Ubuntu:
  47 ``` sh
  48 apt-get install libwxgtk3.0-gtk3-dev libx11-dev libxi-dev libpcre3-dev libxerces-c-dev libuchardet-dev libssh-dev libssl-dev libsmbclient-dev libnfs-dev libneon27-dev libarchive-dev cmake pkg-config g++ git
  49 ```
  50
  51 On Debian unstable/sid:
  52
  53 `apt-get install far2l`
  54
  55 A simple sid back port should be as easy as (build your own binary deb from the official source deb package):
  56
  57 ```
  58 # you will find the latest dsc link at http://packages.debian.org/sid/far2l
  59 dget http://deb.debian.org/debian/pool/main/f/far2l/far2l_2.5.0~beta+git20230223+ds-2.dsc
  60 dpkg-source -x *.dsc
  61 cd far2l-*/
  62 debuild
  63 # cd .. and install your self built far2l*.deb
  64 ```
  65
  66 In older distributions: use libpcre2-dev and libwxgtk3.0-dev instead of libpcre3-dev and libwxgtk3.0-gtk3-dev
  67
  68 #### Clone and Build
  69  * Clone current master `git clone https://github.com/elfmz/far2l`
  70  * Checkout some stable release tag (master considered unstable): `git checkout v_2.#.#`
  71  * Prepare build directory:
  72 ``` sh
  73 mkdir -p far2l/_build
  74 cd far2l/_build
  75 ```
  76
  77  * Build:
  78 _with make:_
  79 ``` sh
  80 cmake -DUSEWX=yes -DCMAKE_BUILD_TYPE=Release ..
  81 cmake --build . -j$(nproc --all)
  82 ```
  83 _or with ninja (you need **ninja-build** package installed)_
  84 ``` sh
  85 cmake -DUSEWX=yes -DCMAKE_BUILD_TYPE=Release -G Ninja ..
  86 cmake --build .
  87 ```
  88
  89  * If above commands finished without errors - you may also install far2l, `sudo cmake --install .`
  90
  91  * Also it's possible to create far2l_2.X.X_ARCH.deb or ...tar.gz packages in `_build` directory by running `cmake --build . --target package` command.
  92
  93 ##### Additional build configuration options:
  94
  95 To build without WX backend (console version only): change `-DUSEWX=yes` to `-DUSEWX=no` also in this case dont need to install libwxgtk\*-dev package
  96
  97 To force-disable TTY|X and TTY|Xi backends: add argument `-DTTYX=no`; to disable only TTY|Xi - add argument `-DTTYXI=no`
  98
  99 To eliminate libuchardet requirement to reduce far2l dependencies by cost of losing automatic charset detection functionality: add -DUSEUCD=no
 100
 101 To build with Python plugin: add argument `-DPYTHON=yes`
 102
 103 To control how RAR archives will be handled in multiarc:
 104  `-DUNRAR=bundled` (default) use bundled sources found in multiarc/src/formats/rar/unrar
 105  `-DUNRAR=lib` use libunrar and unrar utility, also build requires libunrar-dev to be installed
 106  `-DUNRAR=NO` dont use special unrar code, rar archives will be handled by libarchive unless its also disabled
 107
 108 There're also options to toggle other plugins build in same way: ALIGN AUTOWRAP CALC COLORER COMPARE DRAWLINE EDITCASE EDITORCOMP FARFTP FILECASE INCSRCH INSIDE MULTIARC NETROCKS SIMPLEINDENT TMPPANEL
 109
 110 #### OSX/MacOS install
 111
 112  * You can install prebuilt package for x86_64 platform via Homebrew Cask, by command:
 113  ```sh
 114  brew install --cask far2l
 115  ```
 116  * You can also manually download and install prebuilt package for x86_64 platform from Releases page: <https://github.com/elfmz/far2l/releases>
 117  * But if you need custom/recent build, you can proceed to build steps below: using brew or MacPorts.
 118  * Supported compiler: `AppleClang 8.0.0.x` or newer. Check your version, and install/update Xcode if necessary.
 119  ```sh
 120  clang++ -v
 121  ```
 122  * If you want to build using Homebrew - first visit <https://brew.sh/> for installation instructions. Note that there're reported problems with Homebrew-based build under MacOS Big Sur.
 123  * If you want to build using MacPorts - first visit <https://www.macports.org/install.php> for installation instructions.
 124
 125 ##### One line OSX/MacOS install latest far2l git master via unofficial brew tap
 126
 127  * With GUI/TTY backends:
 128 ```sh
 129 brew install --HEAD yurikoles/yurikoles/far2l
 130 ```
 131  * With TTY backend only:
 132 ```sh
 133 brew install --HEAD yurikoles/yurikoles/far2l --without-wxwidgets
 134 ```
 135  * Additionally you can enable python support by adding `--with-python@3.10` to the one of two above commands.
 136
 137 ##### Full OSX/MacOS build from sources (harder):
 138 Some issues can be caused by conflicting dependencies, like having two versions of wxWidgets, so avoid such situation when installing dependencies.
 139
 140  * Clone:
 141 ```sh
 142 git clone https://github.com/elfmz/far2l
 143 cd far2l
 144 ```
 145  * Install needed dependencies with MacPorts:
 146 ``` sh
 147 sudo port install cmake pkgconfig wxWidgets-3.2 libssh openssl xercesc3 libfmt uchardet neon
 148 export PKG_CONFIG_PATH=/opt/local/lib/pkgconfig
 149 ```
 150  * OR if you prefer to use brew packages, then:
 151 ```sh
 152 brew bundle -v
 153 export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:$(brew --prefix)/opt/openssl/lib/pkgconfig:$(brew --prefix)/opt/libarchive/lib/pkgconfig"
 154 ```
 155  * After dependencies installed - you can build far2l:
 156 _with make:_
 157 ```sh
 158 mkdir _build
 159 cd _build
 160 cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DUSEWX=yes -DCMAKE_BUILD_TYPE=Release ..
 161 cmake --build . -j$(sysctl -n hw.logicalcpu)
 162 ```
 163 _or with ninja:_
 164 ```sh
 165 mkdir _build
 166 cd _build
 167 cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DUSEWX=yes -DCMAKE_BUILD_TYPE=Release -G Ninja ..
 168 cmake --build .
 169 ```
 170  * Then you may create .dmg package by running: `cpack` command.
 171 Note that this step sometimes fails and may succeed from not very first attempt.
 172 Its recommended not to do anything on machine while cpack is in progress.
 173 After .dmg successfully created, you may install it by running `open ...path/to/created/far2l-*.dmg`
 174
 175 ##### macOS workaround if far2l in macOS regularly asks permission to folders
 176 After command
 177 ```
 178  sudo codesign --force --deep --sign - /Applications/far2l.app
 179 ```
 180 it is enough to confirm permission only once.
 181
 182 Details see in [`issue`](https://github.com/elfmz/far2l/issues/1754).
 183
 184 #### Building on Gentoo (and derivatives)
 185 For absolute minimum you need:
 186 ```
 187 emerge -avn dev-libs/xerces-c app-i18n/uchardet dev-util/cmake
 188 ```
 189 If you want to build far2l with wxGTK support also install it:
 190 ```
 191 emerge -avn x11-libs/wxGTK
 192 ```
 193 Additionally, for NetRocks you will need:
 194 ```
 195 emerge -avn net-libs/neon net-libs/libssh net-fs/libnfs net-fs/samba
 196 ```
 197 After installing, follow Clone and Build section above.
 198
 199 #### Installing and Building on [NixOS](https://nixos.org/)
 200
 201 To install system-wide, add the `far2l` package to your [`configuration.nix`](https://nixos.org/manual/nixos/stable/index.html#sec-changing-config) `environment.systemPackages` list. To run the application on-demand without affecting the system state, execute `nix-shell -p far2l --command far2l`. These use a package version from your current [channel](https://nixos.wiki/wiki/Nix_channels).
 202
 203 The Far2l adaptation for _nix_ is [a small file on GitHub](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/far2l/default.nix), it tells which Git revision from Far2l repo to fetch, with what dependencies to build it, and how to patch its references to other software to make it run in isolated fashion independently from other versions available in the system.
 204
 205 You can build and run `far2l` package for any revision:
 206 * Directly from GitHub (`NixOS/nixpkgs` repo, or your own fork and branch):
 207  ``` sh
 208 nix-shell -I nixpkgs=https://github.com/<fork>/nixpkgs/archive/<revision-or-branch>.tar.gz -p far2l --command far2l
 209  ```
 210 * From a locally cloned working directory of the repo:
 211 ``` sh
 212 nix-shell -I nixpkgs=/path/to/nixpkgs -p far2l --command far2l
 213 ```
 214
 215 To advance the package to a new Far2l revision, edit the `fetchFromGitHub` set attributes `rev` (revision hash) and `sha256` (revision content hash). **Important!** If you leave the old content hash, the old cached content for that hash might be used without attempting to download the new revision. If you're not expecting the build to break, the easiest would be to make a fork, push the change, and build straight from github.
 216
 217 #### IDE Setup
 218 You can import the project into your favourite IDE like QtCreator, CodeLite, or any other, which supports cmake or which cmake is able to generate projects for.
 219
 220  * **QtCreator**: select "Open Project" and point QtCreator to the CMakeLists.txt in far2l root directory
 221  * **CLion**: the same as **QtCreator**.
 222  * **CodeLite**: use this guide to setup a project: https://wiki.codelite.org/pmwiki.php/Main/TheCMakePlugin (to avoid polluting your source tree, don't create your workspace inside of the far2l directory)
 223
 224 ### Terminals and SSH clients
 225 Supporting extended far2l keyboard shortcuts and clipboard access
 226
 227  * kovidgoyal's kitty (Linux, macOS, *BSD): https://github.com/kovidgoyal/kitty & https://sw.kovidgoyal.net/kitty (TTY|k backend: keys by kovidgoyal's kitty keyboard protocol; turn on OSC 52 in far2l and kitty for clipboard support)
 228  * Wez's Terminal Emulator (Linux, FreeBSD, Windows): https://github.com/wez/wezterm & https://wezfurlong.org/wezterm (TTY|k backend: keys in Linux, FreeBSD by kovidgoyal's kitty keyboard protocol; TTY|w backend: keys in Windows by win32-input-mode, enabled by default; turn on OSC 52 for clipboard support) [kitty keyboard protocol not supported in macOS & Windows]
 229  * iTerm2 (macOS): https://gitlab.com/gnachman/iterm2 & https://iterm2.com (TTY|a backend: keys by iTerm2 "raw keyboard" protocol; turn on OSC 52 for clipboard support)
 230  * Windows Terminal (TTY|w backend: keys by win32-input-mode; turn on OSC 52 for clipboard support)
 231  * Fork of Putty (Windows SSH client) with added far2l TTY extensions support (fluent keypresses, clipboard sharing etc): https://github.com/ivanshatsky/putty4far2l/releases
 232  * Kitty (another fork of Putty) also have far2l TTY extensions support: https://github.com/cyd01/KiTTY
 233  * putty-nd, one more putty fork with extensions support: https://sourceforge.net/p/putty-nd/
 234
 235 ### Useful 3rd-party extras
 236
 237  * A collection of macros for far2l: https://github.com/corporateshark/far2l-macros
 238  * Turbo Vision, TUI framework supporting far2l terminal extensions: https://github.com/magiblot/tvision
 239  * turbo, text editor supporting far2l terminal extensions: https://github.com/magiblot/turbo
 240  * Tool to import color schemes from windows FAR manager 2 .reg format: https://github.com/unxed/far2ltricks/blob/main/misc/far2l_import.pl
 241  * Community wiki & tips (in Russian; unofficial): https://github.com/akruphi/far2l/wiki
 242
 243 ## Notes on porting and FAR Plugin API changes
 244  * See HACKING.md
 245
 246 ## Known issues:
 247 * Only valid translations are English, Russian, Ukrainian and Belarussian (interface only), all other languages require deep correction.