waveguide:
I am trying to make a new Atmel processor not supported by the Arduino cores function
Out of curiosity, which processor?
waveguide:
Is there an official document describing how the core works for supporting a new processor: the cpp files, the directory structure, what files are common to all cores, which ones are for the new processor?
The official document is the Arduino platform specification:
https://arduino.github.io/arduino-cli/latest/platform-specification/
It's important to understand that the term "core" may refer to either of two things:
If you're lucky, you can reference the core of another platform, and thus not need to write your own platform, but this is only possible if your target processor uses the same architecture as another platform.
waveguide:
This is the closest info I found so far:
A Tour Inside Arduino Core: Source Files, How to Make A New Core and Arduino Building Steps - Atadiat
I did a quick read, and the information seems pretty good, but the organization is very strange.
"A Tour inside Arduino Core" is a nice introduction to cores, but if you're interested in the platform as a whole, it's not where I'd start. As I said, some platforms don't even have their own core, so for an introduction to platforms I would have started with the more fundamental boards.txt file.
Now moving on to the "Files System Tour" section:
First, all source file of Arduino core is placed inside the following directory \Arduino\hardware\arduino{the MCU architecture}\cores\arduino.
This is pretty bad. This path is the location of the Arduino AVR Boards platform bundled with the Arduino IDE installation. But the author is being very vague. How is the reader supposed to know where "\Arduino" is? In fact, this could be a different location depending on where you chose to install the Arduino IDE, but the author didn't bother to mention that.
Another point is that if you have installed an updated version of Arduino AVR Boards via Boards Manager, the platform at this location won't even be in use. It can be very confusing if you are making modifications to the files of this bundled platform without realizing that it's not even being used by the Arduino development software.
Also, this only applies if you are using the classic Arduino IDE 1.x. If you're using Arduino CLI or Arduino IDE 2.x, you won't even have this directory, since those tools don't come with a bundled copy of the Arduino AVR Boards platform.
Another place for Arduino third party cores (i.e. ESP8266 core) is in \Users{username}\AppData\Local\Arduino15\packages
They are providing the Windows-specific path here. If you are using Linux or macOS it will be in a different location:
On Linux:
/home/{username}/.arduino15/packages (a.k.a. ~/.arduino15/packages)
On Mac OS X:
/Users/{username}/Library/Arduino15/packages
Tool-chain tools (and even avr-gcc header files) are located in Arduino\hardware\tools{the MCU architecture}
As above, this is only for the toolchain of the Arduino AVR Boards platform bundled with the Arduino IDE.
and here Users{username}\AppData\Local\Arduino15\packages\arduino\tools
As above, this is the Windows specific path.
In addition, packages/arduino/tools only contains the tools provided by the "arduino" vendor. Tools provided by 3rd party vendors will be located under their own vendor folder (e.g., packages/esp8266/tools contains the toolchain for the ESP8266 platform).
One thing they don't mention in this "Files System Tour" is that platforms may also be installed to {sketchbook folder}/hardware (where "{sketchbook folder}" is the folder shown by the Arduino IDE's File > Preferences > Sketchbook location or Arduino CLI's directories.user configuration key). This is often a much more convenient location to use for platform development.
Users\{username}\AppData\Local\Arduino15\packages is the location for the platforms installed via Boards Manager. Adding Boards Manager installation support to a platform adds some extra complexity. It's a very good thing to do to make your platform easy for everyone to install, but if you're just getting started on development, that's not really the first thing you want to think about. It is more difficult to use dedicated toolchains with platforms installed to the sketchbook/user directory, so this is most suitable for when you are developing a platform that uses the toolchain of an existing platform.
How to Make a New Arduino Core
As an example, a clone for avr core will be made. To make a new Arduino core you need two main things:
1- JSON file to describe the new core: its name, versions, boards, tools dependencies, URLs to download files … etc.
2- Core source files packed in .zip, .tar.bz2 or .tar.gz file.
As I just said, these two things are often not needed, and are certainly not considered "main things". Many platform developers went years before finally adding these things to their platform, and some still haven't. If possible, this is the part you want to think about at the very end, after your platform is finished and ready to share with the world.
When that time comes, you can find more information in the Arduino Package Index Specification:
https://arduino.github.io/arduino-cli/latest/package_index_json-specification/
Adding New Arduino Core to IDE Offline
If there is a need to add a core without hosting the core and JSON file on a website. The easy way to do that is to create a file with the core name in the following directory Documents\Arduino\hardware. The full directory would be like:
Documents\Arduino\hardware {core name }{the MCU architecture}
Ah, now the author of the tutorial mentions the possibility of installing platforms to the sketchbook folder, only after completely overwhelming the aspiring platform developer by sending them down the package_index.json rabbit hole.
A very important thing they don't mention is that "Documents\Arduino" is a vague reference to one specific possible location for the sketchbook folder. Your sketchbook folder may be in a different location, in which case putting a platform at Documents\Arduino\hardware \{core name }\{the MCU architecture} will do you no good.
What they call "{core name }" is actually the vendor name.
waveguide:
Can Arduino CLI help make a new core, or is it just to for existing cores?
You can use your new core with Arduino CLI. You could use Arduino CLI to test installing, compiling, uploading, and burning bootloader with the new core, but it doesn't provide any features to actually help make a core. For that, it's about spending some quality time with your favorite text editor, the specifications, and existing platforms as a reference.
So I'd recommend just jumping in and seeing how it goes. As I said, you'll find that studying existing platforms is very helpful. You might start with a very simply platform like damellis/attiny or carlosefr/atmega, which reference most of their components from the Arduino AVR Boards platform, and thus are very minimal.