---
title: "Installation Guide"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Installation Guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>",
  eval     = FALSE
)
```

## Overview

This guide covers installation, mirror setup, dependency checks, and updates
for `evanverse` and related packages.

| Area | Tools |
|---|---|
| Base installation | `install.packages()`, `devtools::install_github()` |
| Mirror configuration | `set_mirror()` |
| Installation and checks | `inst_pkg()`, `check_pkg()` |
| Updates | `update_pkg()` |

```{r load}
library(evanverse)
```

> **Note:** All examples are static (`eval = FALSE`).
> Network-dependent commands require internet access.

---

## 1 Install evanverse

### CRAN release (recommended)

```{r install-cran}
install.packages("evanverse")
```

### GitHub development version

```{r install-github}
install.packages("devtools")
devtools::install_github("evanbio/evanverse")
```

### Minimal vs full dependency install

```{r install-deps}
# Minimal: Depends + Imports only
install.packages("evanverse", dependencies = c("Depends", "Imports"))

# Full: include Suggests
install.packages("evanverse", dependencies = TRUE)
```

---

## 2 Configure Mirrors

### `set_mirror()` - Configure CRAN/Bioconductor mirrors

`set_mirror()` controls mirror sources used by `inst_pkg()` and `update_pkg()`.

```{r set-mirror-basic}
# Set both CRAN + Bioconductor mirrors (default mirror: tuna)
set_mirror()
#> v CRAN mirror set to: https://mirrors.tuna.tsinghua.edu.cn/CRAN
#> v Bioconductor mirror set to: https://mirrors.tuna.tsinghua.edu.cn/bioconductor

# CRAN only
set_mirror("cran", "westlake")

# Bioconductor only
set_mirror("bioc", "official")
```

Supported mirror names:

| Scope | Mirrors |
|---|---|
| CRAN | `official`, `rstudio`, `tuna`, `ustc`, `aliyun`, `sjtu`, `pku`, `hku`, `westlake`, `nju`, `sustech` |
| Bioconductor | `official`, `tuna`, `ustc`, `westlake`, `nju` |

CRAN-only mirrors cannot be used with `repo = "all"`:

```{r set-mirror-error}
set_mirror("all", "aliyun")
#> Error in `set_mirror()`:
#> ! Mirror "aliyun" is CRAN-only and cannot be used with repo = "all".
```

---

## 3 Install Other Packages With evanverse

### `inst_pkg()` - Install from CRAN, GitHub, Bioconductor, or local file

```{r inst-cran}
inst_pkg("dplyr", source = "CRAN")
```

```{r inst-github}
inst_pkg("hadley/emo", source = "GitHub")
```

```{r inst-bioc}
inst_pkg("DESeq2", source = "Bioconductor")
```

```{r inst-local}
inst_pkg(source = "Local", path = "mypackage_1.0.0.tar.gz")
```

Local installation requires `path`:

```{r inst-local-error}
inst_pkg(source = "Local")
#> Error in `inst_pkg()`:
#> ! Must provide `path` for local installation.
```

Already-installed packages are skipped automatically.

---

## 4 Verify Installation Status

### `check_pkg()` - Check and optionally auto-install missing packages

```{r check-basic}
check_pkg("ggplot2", source = "CRAN")
#> # A tibble: 1 x 4
#>   package name    installed source
#>   <chr>   <chr>   <lgl>     <chr>
#> 1 ggplot2 ggplot2 TRUE      CRAN
```

```{r check-multiple}
check_pkg(c("ggplot2", "fakepkg123"), source = "CRAN")
#> v Installed: ggplot2
#> ! Missing: fakepkg123
```

```{r check-auto}
check_pkg(c("ggplot2", "fakepkg123"), source = "CRAN", auto_install = TRUE)
#> i Installing missing packages automatically...
```

For GitHub source, use `"user/repo"` format:

```{r check-github}
check_pkg("r-lib/devtools", source = "GitHub")
```

---

## 5 Update Packages

### `update_pkg()` - Update all packages or specific targets

```{r update-all}
# Update all CRAN + Bioconductor packages
update_pkg()
```

```{r update-cran-only}
# CRAN only
update_pkg(source = "CRAN")
```

```{r update-specific}
# Specific package(s)
update_pkg("ggplot2", source = "CRAN")
update_pkg("hadley/ggplot2", source = "GitHub")
update_pkg("DESeq2", source = "Bioconductor")
```

If `pkg` is provided, `source` must also be provided (cannot stay at `"all"`).

---

## 6 Troubleshooting

### Package not available

```{r check-r-version}
R.version.string
```

If your R version is too old, upgrade R and retry.

### Bioconductor install problems

```{r install-biocmanager}
if (!requireNamespace("BiocManager", quietly = TRUE)) {
  install.packages("BiocManager")
}
BiocManager::install(c("Biobase", "GSEABase", "biomaRt", "GEOquery"))
```

### Corporate network / proxy issues

```{r proxy}
Sys.setenv(http_proxy = "http://your-proxy:port")
Sys.setenv(https_proxy = "https://your-proxy:port")
```

### Local library permission issues

```{r user-lib}
install.packages("evanverse", lib = Sys.getenv("R_LIBS_USER"))
```

---

## 7 A Combined Workflow

The following sequence is practical for a fresh environment:

```{r workflow}
# 1) Install evanverse
install.packages("evanverse")
library(evanverse)

# 2) Set mirrors
set_mirror("all", "tuna")

# 3) Install key dependencies
inst_pkg(c("dplyr", "ggplot2"), source = "CRAN")
inst_pkg("DESeq2", source = "Bioconductor")

# 4) Verify status
check_pkg(c("dplyr", "ggplot2", "DESeq2"), source = "CRAN")

# 5) Keep packages updated
update_pkg(source = "CRAN")
```

---

## Getting Help

- `?set_mirror`, `?inst_pkg`, `?check_pkg`, `?update_pkg`
- [CRAN Package Page](https://cran.r-project.org/package=evanverse)
- [GitHub Issues](https://github.com/evanbio/evanverse/issues)
