Arquivos / diretórios não padrão, Rbuildignore e inst

cupom com desconto - o melhor site de cupom de desconto cupomcomdesconto.com.br


[Esteartigofoipublicadopelaprimeiravezem[Thisarticlewasfirstpublishedon Publicações no blog do R-hub, e gentilmente contribuiu para os R-blogueiros]. (Você pode relatar um problema sobre o conteúdo desta página aqui)


Deseja compartilhar seu conteúdo com R-blogueiros? clique aqui se você tiver um blog ou aqui se não tiver.

Para dividir a gravação de extensões R, um pacote R é “Diretório de arquivos que estendem R”.
Esses arquivos precisam seguir uma estrutura padrão: não é possível armazenar tudo o que você gosta em um arquivo que você envia ao CRAN.
Neste post, veremos quais diretórios e arquivos lata vá para o CRAN e como navegar por isso enquanto envia tudo o que deseja para CRAN e mantém algumas coisas apenas na origem do pacote.

Diretório e arquivos conhecidos e padrão

No momento da redação deste artigo, o que um pacote criado pode conter é esta lista chamada known1 1 definido na fonte R, em tools/R/check.R.

known <- c("DESCRIPTION", "INDEX", "LICENCE", "LICENSE",
           "LICENCE.note", "LICENSE.note",
           "MD5", "NAMESPACE", "NEWS", "PORTING",
           "COPYING", "COPYING.LIB", "GPL-2", "GPL-3",
           "BUGS", "Bugs",
           "ChangeLog", "Changelog", "CHANGELOG", "CHANGES", "Changes",
           "INSTALL", "README", "THANKS", "TODO", "ToDo",
           "INSTALL.windows",
           "README.md", "NEWS.md",
           "configure", "configure.win", "cleanup", "cleanup.win",
           "configure.ac", "configure.in",
           "datafiles",
           "R", "data", "demo", "exec", "inst", "man",
           "po", "src", "tests", "vignettes",
           "build",       # used by R CMD build
           ".aspell",     # used for spell checking packages
           "java", "tools", "noweb") # common dirs in packages.

Nesta postagem, não abordaremos o que esses diretórios e arquivos podem conter e como devem ser formatados, o que é outro padrão.
Vamos nos concentrar na mera existência deles.

Arquivos não padrão

Agora, em uma pasta de pacote, você pode ter todos os tipos de coisas diferentes

  • alguns arquivos de configuração para integração contínua, por pkgdown site, etc;
  • a fonte de um aplicativo brilhante;
  • cran-comments.md para envios de CRAN.

Se eles acabassem na raiz do pacote, a verificação do R CMD reclamaria e informaria

😡 Arquivos / diretórios não padrão encontrados no nível superior:

Observe que às vezes a verificação do R CMD pode reclamar sobre arquivos que você não vê na fonte, porque eles são criados pelo processo de verificação.
Nesse caso, dê um passo atrás e tente corrigir seu código, por exemplo, limpando depois de si mesmo, se exemplos criarem arquivos.

Agora, como você mantém os itens que despertam alegria no pacote fornecido e na origem do pacote, sem comprometer a aprovação da verificação R CMD?

Excluindo arquivos do pacote empacotado

Existem arquivos que não precisam transformá-lo em um pacote incorporado (por exemplo, seus comentários do CRAN, seus pkgdown config.).

Filtragem de criação do R CMD

Para impedir que arquivos e pastas passem da origem do pacote para o pacote empacotado, precisamos entender como as coisas funcionam:
Como os arquivos e diretórios acabam, ou não, no pacote tarball / pacote configurável, do pacote de origem?
Esse é um trabalho do R CMD build, possivelmente por meio de um wrapper como devtools::build().
Ele copiará toda a fonte do pacote e removerá os arquivos em três “etapas”2

  • Arquivos listados em .Rbuildignore;
## Check for files listed in .Rbuildignore or get_exclude_patterns()
inRbuildignore <- function(files, pkgdir) {
    exclude <- rep.int(FALSE, length(files))
    ignore <- get_exclude_patterns()
    ## handle .Rbuildignore:
    ## 'These patterns should be Perl regexps, one per line,
    ##  to be matched against the file names relative to
    ##  the top-level source directory.'
    ignore_file <- file.path(pkgdir, ".Rbuildignore")
    if (file.exists(ignore_file))
	ignore <- c(ignore, readLines(ignore_file, warn = FALSE))
    for(e in ignore[nzchar(ignore)])
	exclude <- exclude | grepl(e, files, perl = TRUE,
				ignore.case = TRUE)
    exclude
}
  • E alguns padrões de exclusão padrão
get_exclude_patterns <- function()
    c("^\.Rbuildignore$",
      "(^|/)\.DS_Store$",
      "^\.(RData|Rhistory)$",
      "~$", "\.bak$", "\.swp$",
      "(^|/)\.#[^/]*$", "(^|/)#[^/]*#$",
      ## Outdated ...
      "^TITLE$", "^data/00Index$",
      "^inst/doc/00Index\.dcf$",
      ## Autoconf
      "^config\.(cache|log|status)$",
      "(^|/)autom4te\.cache$", # ncdf4 had this in subdirectory 'tools'
      ## Windows dependency files
      "^src/.*\.d$", "^src/Makedeps$",
      ## IRIX, of some vintage
      "^src/so_locations$",
      ## Sweave detrius
      "^inst/doc/Rplots\.(ps|pdf)$"
      )
  • E mais algumas exclusões prontas para uso
exclude <- inRbuildignore(allfiles, pkgdir)

isdir <- dir.exists(allfiles)
## old (pre-2.10.0) dirnames
exclude <- exclude | (isdir & (bases %in%
                               c("check", "chm", .vc_dir_names)))
exclude <- exclude | (isdir & grepl("([Oo]ld|\.Rcheck)$", bases))
## FIXME: GNU make uses GNUmakefile (note capitalization)
exclude <- exclude | bases %in% c("Read-and-delete-me", "GNUMakefile")
## Mac resource forks
exclude <- exclude | startsWith(bases, "._")
exclude <- exclude | (isdir & grepl("^src.*/[.]deps$", allfiles))
## Windows DLL resource file
exclude <- exclude | (allfiles == paste0("src/", pkgname, "_res.rc"))
## inst/doc/.Rinstignore is a mistake
exclude <- exclude | endsWith(allfiles, "inst/doc/.Rinstignore") |
    endsWith(allfiles, "inst/doc/.build.timestamp") |
    endsWith(allfiles, "vignettes/.Rinstignore")
## leftovers
exclude <- exclude | grepl("^.Rbuildindex[.]", allfiles)
        ## or simply?  exclude <- exclude | startsWith(allfiles, ".Rbuildindex.")
        exclude <- exclude | (bases %in% .hidden_file_exclusions)

De particular interesse é .vc_dir_names: você notou sua .git pasta magicamente não foi incluída no pacote fornecido?3

Leia Também  O consórcio R dá as boas-vindas ao novo membro ThinkR, R, empresa de engenharia de ciência de idiomas e dados
cupom com desconto - o melhor site de cupom de desconto cupomcomdesconto.com.br
## Version control directory names: CVS, .svn (Subversion), .arch-ids
## (arch), .bzr, .git, .hg (mercurial) and _darcs (Darcs)
## And it seems .metadata (eclipse) is in the same category.

.vc_dir_names <-
    c("CVS", ".svn", ".arch-ids", ".bzr", ".git", ".hg", "_darcs", ".metadata")

E .hidden_file_exclusions

## We are told
## .Rproj.user is Rstudio
## .cproject .project .settings are Eclipse
## .exrc is for vi
## .tm_properties is Mac's TextMate
.hidden_file_exclusions <-
    c(".Renviron", ".Rprofile", ".Rproj.user",
      ".Rhistory", ".Rapp.history",
      ".tex", ".log", ".aux", ".pdf", ".png",
      ".backups", ".cvsignore", ".cproject", ".directory",
      ".dropbox", ".exrc", ".gdb.history",
      ".gitattributes", ".gitignore", ".gitmodules",
      ".hgignore", ".hgtags",
      ".htaccess",
      ".latex2html-init",
      ".project", ".seed", ".settings", ".tm_properties")

Observe que R CMD build vai silenciosamente remova arquivos do pacote fornecido, que é uma fonte de erros estranhos.
Por exemplo, se você escreveu um padrão errado em .Rbuildignore que acaba removendo um dos seus arquivos R, a verificação do R CMD se queixará de uma função inexistente e você pode ficar um pouco confuso.

.Rbuildignore

Portanto, se a origem do pacote apresentar qualquer arquivo ou diretório que não seja conhecido, não padrão e também não listado nas exclusões comuns, será necessário adicioná-lo ao .Rbuildignore.

Conforme escrito em “Escrevendo extensões R”, “Para excluir arquivos de serem colocados no pacote, é possível especificar uma lista de padrões de exclusão no arquivo .Rbuildignore no diretório de origem de nível superior. Esses padrões devem ser expressões regulares do tipo Perl (consulte a ajuda do regexp no R para obter detalhes precisos), um por linha, para corresponder sem distinção entre maiúsculas e minúsculas nos nomes de arquivos e diretórios relativos ao diretório de origem do pacote de nível superior “..

Abaixo está knitr .Rbuildignore

.gitignore
tikzDictionary$
aux$
log$
out$
inst/examples/knitr-.*.pdf
inst/examples/child/knitr-.*.pdf
inst/examples/child/knitr-.*.md
inst/examples/figure
inst/examples/cache
knitr-minimal.md
knitr-spin.md
png$
^.Rproj.user$
^.*.Rproj$
^.travis.yml$
FAQ.md
Makefile
^knitr-examples$
^.github$
^docs$
^README-ES.md$
^README-PT.md$
^codecov.yml$
^NEWS.md$

Como editar .Rbuildignore?

Você pode editar .Rbuildignore manualmente, na linha de comando ou usando usethis::use_build_ignore() que escapará dos caminhos por padrão.
Há também o usethis::edit_r_buildignore() função para criar / abrir o nível do usuário ou do projeto .Rbuildignore.

Quando editar .Rbuildignore?

Você pode editar .Rbuildignore quando a verificação do R CMD reclama, ou ao criar arquivos não padrão.
É aqui que as ferramentas de fluxo de trabalho podem ajudar.
Se você p. usar usethis::use_cran_comments() para criar cran-commends.md, ele também será adicionado a .Rbuildignore

Mantendo itens não padronizados no pacote incluído

Agora você deve se perguntar: como empacotar um aplicativo Shiny, um arquivo de dados brutos etc. se eles não são permitidos na raiz de um pacote empacotado?
Bem, fácil, mantenha-os, mas não na raiz, ah!
Mais seriamente, uma boa idéia é examinar as práticas existentes nos pacotes CRAN recentes.
Muitas vezes, você verá coisas armazenadas em inst/: elementos clássicos como informações de citação em inst/CITATION4, dados brutos em inst/extdata/ mas também elementos mais modernos ou exóticos, como os complementos do RStudio.

Leia Também  Calibrar a conferência Blockchain educa e encanta o público com palestrantes de classe mundial

E o .Rinstignore?

.Rbuildignore tem um irmão chamado .Rinstignore para outro caso de uso: “O conteúdo do subdiretório inst será copiado recursivamente para o diretório de instalação. Os subdiretórios de inst não devem interferir com os usados ​​por R (atualmente, R, dados, demo, exec, libs, man, help, html e Meta, e versões anteriores usavam látex, R-ex). A cópia do inst acontece após a construção do src, para que o Makefile possa criar arquivos a serem instalados. Para excluir a instalação de arquivos, é possível especificar uma lista de padrões de exclusão no arquivo .Rinstignore no diretório de origem de nível superior. Esses padrões devem ser expressões regulares do tipo Perl5 (consulte a ajuda do regexp em R para obter detalhes precisos), um por linha, para corresponder sem distinção entre maiúsculas e minúsculas nos caminhos de arquivo e diretório, por exemplo doc /.*[.]png $ excluirá todos os arquivos PNG em inst / doc com base na extensão. “

Veja por exemplo future.apply .Rinstignore

# Certain LaTeX files (e.g. bib, bst, sty) must be part of the build 
# such that they are available for R CMD check.  These are excluded
# from the install using .Rinstignore in the top-level directory
# such as this one.
doc/.*[.](bib|bst|sty)$

Conclusão

Neste post, explicamos quais arquivos e diretórios podem estar presentes em um pacote empacotado.
Também explicamos como impedir que coisas fora do padrão passem da origem do pacote para o pacote empacotado: using .Rbuildignore; e como deixar coisas fora do padrão entrar no pacote incluído: inst/ – mas não faça dela a sua gaveta de lixo, é claro.
Vamos terminar com uma citação de A mágica de arrumar as vidas de Marie Kondo

“Mantenha apenas as coisas que falam ao seu coração.”

… que precisamos alterar …

“Mantenha apenas as coisas que falam com seu cheque R CMD.”


  1. Eu poderia ter entrado em uma toca de coelho olhando através de arquivos THANKS no espelho R-hub do código-fonte CRAN.
    Eu com certeza gosto de ler agradecimentos. 💐 ↩

  2. Esse procedimento pode tornar o R ​​CMD muito lento quando você possui grandes diretórios ocultos; consulte este excelente thread do R-package-devel. ↩

  3. Sou fascinado por exclusões comuns, que refletem o que é aceito como prática comum. ↩

  4. Essa citação será encontrada pelo citation() função quando um usuário chama, por exemplo citation("stplanr"), e por pkgdown ao criar o site, consulte stplanr Página CITATION vinculada a sua página inicial. ↩

  5. Outro arquivo cheio de regex Perl que está fora do escopo desta postagem é .install_extras que influencia o que faz (e não o que não faz) do vignettes para inst/doc ao construir o pacote. ↩

Leia Também  Preconceito de colisor, ou: as gostosas são escuras e se beijam feio?

var vglnk = {key: ‘949efb41171ac6ec1bf7f206d57e90b8’};

(função (d, t) {
var s = d.createElement
s.src = ‘//cdn.viglink.com/api/vglnk.js’;
var r = d.getElementsByTagName
} (documento, ‘script’));

Para Deixe um comentário para o autor, siga o link e comente no blog: Publicações no blog do R-hub.

R-bloggers.com oferece atualizações diárias por email sobre notícias e tutoriais do R sobre o aprendizado do R e muitos outros tópicos. Clique aqui se você deseja publicar ou encontrar um emprego em ciência da dados / R.


Deseja compartilhar seu conteúdo com R-blogueiros? clique aqui se você tiver um blog ou aqui se não tiver.



cupom com desconto - o melhor site de cupom de desconto cupomcomdesconto.com.br