create.qmd

# Packages FAQ

```{r}
#| eval: true 
#| echo: false 
#| include: false
source("_common.R")
```

```{r}
#| label: co_box_dev
#| echo: false
#| results: asis
#| eval: false
co_box(
  color = "r", 
  look = "minimal",
  header = "Alert",
  contents = "The contents for section are being revised. Thank you for your patience."
)
```

## *Can an `.Rproj` file convert an R project into an R package?*

The technical answer is no, because the `.Rproj` only activates the **Build** pane in the IDE. The tools in the **Build** pane are directly connected to the [`devtools` package](https://devtools.r-lib.org/) (hence the `PackageUseDevtools: Yes` in the `.Rproj` file). 

The seven mandatory fields are required in the `DESCRIPTION` to have a functioning R package.

## *I have a `DESCRIPTION` file with the required fields, but where is the **Build** pane?*

If the mandatory fields are added to the `DESCRIPTION`, but the `.Rproj` file doesn't have any of the package configuration fields, then the **Build** pane will not be displayed (see example below):

::: {#fig-build_pane_tools}

![Build pane tools](img/shiny_app_pkg_ide_desc_no_build.png){#fig-build_pane_tools height="100%" width="100%" fig-align="center"}

Mandatory `DESCRIPTION` fields with package configuration in `.Rproj` file
:::

## *What if my `.Rproj` file is configured to work with a package, but my `DESCRIPTION` file is missing one (or more) of the required fields?*

Setting the **Project build tools** in your **Project Options** is insufficient to convert a project into a package. If the `.Rproj` file has the package development fields (i.e., **Project build tools** to **Package**) but the mandatory fields are missing from the `DESCRIPTION` file, the **Build** pane will be triggered:

::: {#fig-shiny_app_ide_desc}
![`DESCRIPTION`](img/shiny_app_ide_desc.png){#fig-shiny_app_ide_desc width="100%" fig-align="center"}

Unchanged `DESCRIPTION` file after changing `.Rproj`
:::

But trying to load the code in the `R/` folder with **Build** > **Load All** (or `devtools::load_all()`) we return the following error: 

```{r}
#| eval: false
#| code-fold: false
install.packages("devtools")
library(devtools)
devtools::load_all()
```

::: {#fig-load_all_error}
![Build pane tools](img/02_pkgs_load_all_error.png){#fig-load_all_error height="100%" width="100%" fig-align="center"}

Attempt to `load_all()` code in `R/` folder
:::

The directory must include a `DESCRIPTION` file containing the mandatory fields *and* an `.Rproj` file with the package configuration fields listed above to be a functional R package.


Read more about `DESCRIPTION` file fields in [R Packages, 2ed](https://r-pkgs.org/description.html#the-description-file)

```{r}
#| label: co_box_rproj
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "g",
  header = "RStudio project files",
  contents = "
You can read more about the benefits of using RStudio projects to configuring project-level options [here](https://support.posit.co/hc/en-us/articles/200526207-Using-RStudio-Projects).  
  ", fold = FALSE
)
```

## *I have the mandatory fields in my `.Rproj` file and `DESCRIPTION`, but still no **Build** pane?*

To get the IDE to re-read the `.Rproj` file, you *might* have to terminate the session (**Session** > **Terminate R...** > **Yes**)

::: {#fig-terminate layout-ncol=2}

![Session > Terminate](img/terminate_session.png){#fig-terminate_session width=50%}

![Click Yes](img/terminate_yes.png){#fig-terminate_yes width=50%}

Terminate your R session
:::

This prompts the IDE to re-read the `.Rproj` file and trigger the **Build** pane.