Installing gnparser

2024-12-18

Source: vignettes/help/installing_gnparser.Rmd

This tutorial will guide you through the installation of gnparser, a required binary file for using our R package. The installation process varies depending on your operating system (Windows, macOS, or Linux).

We provide two installation options: using reproducible code or following a manual step-by-step installation. The first option is a quick and easy way to install the software. In case of errors, you can try the manual step-by-step approach.

Option 1: Run the following code

Installing and loading bdc package


⚠ Important: Get the latest version of gnparser. The execution of this step is required independently of our operation system.

  get_latest_gnparser_version <- function() {
    url <- "https://github.com/gnames/gnparser/releases"
    
    # Reads the content of the releases page
    page <- xml2::read_html(url)
    
    # Extracts the first tag containing the version, using a CSS selector
    version <- page %>%
      rvest::html_element(".Link--primary") %>%
      rvest::html_text2()
    
    version <- gsub("v", "", version)
    return(version)
  }

  latest_version <- get_latest_gnparser_version()
  message("Latest version of gnparser: ", latest_version)

Windows

Download the lastest version of gnparser

link <- "https://github.com/gnames/gnparser/releases/download/"
url_latest_version = paste0(link, "v", latest_version, "/gnparser-v", latest_version, "-win-arm.zip")
file_name = here::here(paste0(latest_version, ".zip"))
                      
download.file(url_latest_version, file_name)

Move file to the recommended directory

# Extracts the file in a temporary directory
unzip(file_name, exdir = here::here())

# Sets the destination filename
AppData_path <- Sys.getenv("AppData")

# Moves the executable to the target directory
file.copy("gnparser.exe", AppData_path, recursive = TRUE)


Linux

Download the lastest version of gnparser

link <- "https://github.com/gnames/gnparser/releases/download/"
url_latest_version = paste0(link, "v", latest_version, "/gnparser-v", latest_version, "-linux-arm.tar.gz")
file_name = here::here(paste0(latest_version, ".tar.gz"))
                      
download.file(url_latest_version, file_name)

Move file to the recommended directory

# Extracts the file in a temporary directory
untar(file_name, exdir = here::here())

# Moves the executable to the target directory
file.copy(here::here("gnparser"), "~/bin")


macOS

⚠️IMPORTANT: Before installing gnparser, it is highly recommend to install Homebrew, which is a package manager for macOS and Linux that simplifies the installation of software and libraries directly from the terminal. You can use the steps below to install Homebrew. Moreover, a detailed explanation on how to install homebrew can be found in this video.

  1. Open Terminal

    • Press Command + Space to open Spotlight Search
    • Type “Terminal” and press Enter
    • A new window will appear - this is your Terminal

  2. Using Homebrew (Recommended)

    • In the Terminal window, paste and run these commands:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  1. Install gnparser using brew 
brew tap gnames/gn 
brew install gnparser

After that, close the terminal and refresh the R section.


Option 2: Manual Installation

Windows

  1. Download the installer

    • Go to gnparser releases
    • Download the Windows version (file ending in -win-64.zip)
    • Save it to a known location on your computer

  2. Open Command Prompt

    • Press Windows + R on your keyboard
    • Type cmd and press Enter
    • A black window will appear - this is your Command Prompt

  3. Create installation directory

    • In the Command Prompt window, type:
    mkdir C:\bin

  4. Extract and move the file

    • Extract the downloaded zip file

    • Copy the gnparser.exe file to C:using either:

      • Windows Explorer (drag and drop)
      • Or Command Prompt:
      copy path\to\downloaded\gnparser.exe C:\bin

  5. Add to System Path

    • Press Windows + X and select “System”
    • Click “Advanced system settings”
    • Click “Environment Variables”
    • Under “System variables”, find and select “Path”
    • Click “Edit”
    • Click “New”
    • Add C:\bin
    • Click “OK” on all windows

  6. Verify installation

    • Open a new Command Prompt window
    • Type:
    gnparser --version
    • If you see a version number, the installation was successful


Linux

  1. Open Terminal

    • Press Ctrl + Alt + T (on most Linux distributions)
    • Or find Terminal in your applications menu
    • A new window will appear - this is your Terminal

  2. Download the binary

    • In the Terminal window, run these commands:
    # Create a temporary directory
mkdir -p ~/tmp
cd ~/tmp

# Download the latest Linux version
wget https://github.com/gnames/gnparser/releases/download/v1.10.1/gnparser-v1.10.1-linux.tar.gz

# Extract the file
tar xvf gnparser-*.tar.gz

# Move to system directory
sudo mv gnparser /usr/local/bin

  3. Verify installation

    bash gnparser --version


macOS

  1. Open Terminal

    • Press Command + Space to open Spotlight Search
    • Type “Terminal” and press Enter
    • A new window will appear - this is your Terminal

  2. Using Homebrew (Recommended)

    • In the Terminal window, paste and run these commands:
    # Install Homebrew if you haven't already
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install gnparser
brew tap gnames/gn
brew install gnparser

  3. Manual Installation

    • Download the macOS version (file ending in -mac.tar.gz) from gnparser releases
    • Open Terminal (Applications > Utilities > Terminal)
    • Navigate to the download directory:
    cd ~/Downloads
    • Extract the file:
    tar xvf gnparser-v*.tar.gz
    • Move to system directory:
    sudo mv gnparser /usr/local/bin
    • You may need to allow the application in System Preferences:
      • Go to System Preferences > Security & Privacy
      • Click the lock to make changes
      • Allow gnparser to run ```


Troubleshooting

If you encounter any issues:

  1. Command not found

    • Make sure you’ve added the correct directory to your system PATH
    • Try closing and reopening your terminal/command prompt

  2. Permission denied

    • On macOS/Linux, you may need to make the file executable:
    chmod +x /usr/local/bin/gnparser

  3. Security warnings

    • On macOS: Go to System Preferences > Security & Privacy and allow the application
    • On Windows: You might need to run as administrator

Testing the Installation

After installation, test if gnparser is working correctly:

# In R, try parsing a scientific name
test <-
  bdc::bdc_clean_names(c("OCOTEA odorifera", "ocotea odorifera", "ocotea cf. odorifera"))